---
name: satellite-sat-toolchain-tutorial
title: Deploying apps to clusters with Continuous Delivery and Satellite Config
description: Deploy Kubernetes resources, like deployments, from your GitHub or GitLab repository to multiple clusters with IBM Cloud® Continuous Delivery and Satellite Config.
last-updated: 2026-08-14
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/satellite?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Deploying apps to clusters with Continuous Delivery and Satellite Config
{: #sat_toolchain_tutorial}
{: toc-content-type="tutorial"}
{: toc-services="satellite, ContinuousDelivery"}
{: toc-completion-time="30m"}

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

## Objectives
{: #sat_toolchain_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
{: #sat_toolchain_audience}

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

## Prerequisites
{: #toolchain-prereq}

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

* An [IBM Cloud account](https://cloud.ibm.com/registration){: external}. 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](https://cloud.ibm.com/docs/account?topic=account-account-getting-started&format=markdown) and [Upgrading your account](https://cloud.ibm.com/docs/account?topic=account-upgrading-account&format=markdown).

* 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](https://cloud.ibm.com/docs/satellite?topic=satellite-register-openshift-clusters&format=markdown).
{: tip}

* A [Satellite cluster group](https://cloud.ibm.com/docs/satellite?topic=satellite-setup-clusters-satconfig&format=markdown) 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](https://cloud.ibm.com/docs/openshift?topic=openshift-registry&format=markdown#cluster_registry_auth).

* A Satellite location for deploying the resources.

* An instance of the [Continuous Delivery](https://cloud.ibm.com/docs/ContinuousDelivery?topic=ContinuousDelivery-getting-started&format=markdown) service.

## Getting started
{: #welcome}
{: step}

Start to create a toolchain in IBM Cloud. 
{: shortdesc}

1. Log in to [IBM Cloud Toolchains](https://cloud.ibm.com/devops/toolchains) with your IBM Cloud credentials. 
2. Select the Resource Group and Location for your toolchain.
3. Click **Create toolchain**.
4. On the **Create a Toolchain** page, select **Satellite** under **Filters** to display templates that are applicable for Satellite.
5. Select the **Deploy Kubernetes resources to multiple clusters** template.
6. Read through the information to understand how toolchains work and then click **Start**.

## Defining toolchain settings
{: #toolchain_settings}
{: step}

Define the name, region, and resource group for the toolchain. 
{: shortdesc}

1. Provide the name for the toolchain.
2. Select the region where you want the toolchain to be created.
3. Select a resource group where you want the toolchain to be created.
4. Click **Continue**. 

## Defining your source repository
{: #source_repository}
{: step}

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.
{: shortdesc}

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

2. 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`. 
   
3. 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**. 
{: tip}

## Setting up your delivery pipeline
{: #pipeline_settings}
{: step}

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

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

2. Click **Continue**.

## Providing an API key
{: #secrets}
{: step}

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

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

1. Select the secret provider or providers that you use. You can select one or more.

2. Click **Continue**. 

3. 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
{: #satellite_config}
{: step}

Specify the settings that the Satellite Config tool can use when deploying resources.
{: shortdesc}


1. 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.
    {: tip}

2. Define the namespace that you want your resources to be deployed to. This must be an existing namespace.

3. Specify the branch to deploy the resource to; for example, `v1`.

4. Provide the path to deploy the resource to; for example, `deployments`.

5. Select the cluster group to receive the resources that you are deploying.

6. Provide the displayed name of the Satellite configuration.

7. Click **Continue**. 

## Reviewing the summary
{: #summary}
{: step}

Review the summary and confirm to create your toolchain.
{: shortdesc}

- To change any parameters you provided earlier, click **Back**.

- To create the toolchain with the provided parameters, click **Create toolchain**.

## Testing the toolchain
{: #test_toolchain}
{: step}

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. 
{: shortdesc}

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](#modify_trigger).

To start a manual pipeline run, follow these steps.

1. On the **Overview** of your toolchain under **Delivery pipelines**, select the delivery pipeline to view its status.
2. Click **Run pipeline**. 
3. Review the trigger properties to make sure that they match your configuration.
4. Click **Run** to run the toolchain and deploy your app.
5. Optional: Click the name of the run to see the status, logs, and details.
6. Optional: After the app is running, go to [Satellite Configuration](https://cloud.ibm.com/satellite/configuration) or run `ibmcloud sat config` command to see your Satellite Config resources.
    
## Verifying that the sample app is running
{: #verify_app}
{: step}

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

1. From the [Clusters](https://cloud.ibm.com/satellite/clusters){: external} page, click the cluster that you used to deploy your app.
2. Click **OpenShift web console**.
3. In the **Workloads** > **Pod** section, filter by the project or the cluster namespace, and verify that the pods are running.
4. In the **Networking** > **Routes** section, filter by the project or the cluster namespace, and locate the app URL.
5. Verify that the app is running by visiting the app URL with your browser.
6. Optional: You can view your Satellite configuration [in the console](https://cloud.ibm.com/satellite/configuration), or by running the `ibmcloud sat config ls` [command](https://cloud.ibm.com/docs/satellite?topic=satellite-satellite-cli-reference&format=markdown#config-ls-cli).

## Deploying a new version of your app from a different branch
{: #modify_trigger}
{: step}

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.
{: shortdesc}

1. On the **Overview** of your toolchain, select the delivery pipeline to modify.
2. Click **Triggers**.
3. Click the action menu for the **commit-push** trigger.
4. Select **Edit**.
5. In the **Branch** field, select the branch you want to deploy. For example, `v2`.
6. In the **deployment-branch** line under **Properties**, click the **Edit** icon.
7. Modify the value of this property to the branch name you want to deploy. For example, `v2`.
8. Save the changes.
9. Check your app to see if it is running the new version by visiting the app URL with your browser.
10. Optional: View the new version of your configuration in the Satellite configurations [console](https://cloud.ibm.com/satellite/configuration) or by running running the `ibmcloud sat config get --config CONFIG` [command](https://cloud.ibm.com/docs/satellite?topic=satellite-satellite-cli-reference&format=markdown#config-get-cli).

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