IBM Cloud Docs
Deploy Kubernetes resources to multiple clusters by using IBM Cloud Satellite Config

Deploy Kubernetes resources to multiple clusters by using IBM Cloud Satellite Config

In this tutorial, you learn how to create an open toolchain by using IBM Cloud® Continuous Delivery and deploy your application (app) by using IBM Cloud Satellite. 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.

IBM Cloud Satellite brings public cloud services to any environment, allowing customers with stringent regulatory requirements to use the flexibility and agility of these services for their secure on-premises data center. Continuous Delivery uses Satellite Config to deploy an app across a group of clusters in IBM Cloud Satellite. With Satellite Config, you create a configuration to specify which Kubernetes resources you want to deploy to a cluster group of Kubernetes or Red Hat® OpenShift® clusters that are running in your Satellite location or in IBM Cloud.

The toolchain that is used in this tutorial implements standard DevOps practices around continuous delivery capabilities. After you make sure that you meet all of the continuous integration requirements, this toolchain helps you to manage your deployments in IBM Cloud 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.

Tekton is an open source, vendor-neutral, Kubernetes-native framework that you can use to build, test, and deploy apps. Tekton provides a set of shared components for implementing continuous delivery systems. As an open source project, Tekton is managed by the Continuous Delivery Foundation. The goal is to modernize continuous delivery by providing industry specifications for pipelines, workflows, and other building blocks. With Tekton, you can build, test, and deploy across cloud providers or on-premises systems by abstracting the underlying implementation details. Tekton pipelines are built into Continuous Delivery.

The template that is used in this tutorial works with the Standard plan for Red Hat OpenShift.

Before you begin

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

  • An instance of the Continuous Delivery service.

  • Optional. Secrets that are stored in a secrets management vault and managed centrally from a single location. For more information about choosing from the various secrets management and data protection offerings, see Managing IBM Cloud secrets. If you don't already have an instance of the secrets management vault provider of your choice, create one.

  • Optional. A namespace that is created by using the container registry command line. To create a namespace, type the following command from the command line:

    ibmcloud cr namespace-add <my namespace>

    Alternatively, you can create a namespace on the Container Registry page. For more information about creating a namespace in this location, see IBM Cloud Container Registry service.

Related content

Create the toolchain

In this step, you create a Deploy your application to multiple clusters toolchain. The target Kubernetes cluster is configured during the toolchain setup by using your IBM Cloud API key and your Kubernetes cluster name. You can change these settings later by updating the Delivery Pipeline configuration. Any code that is merged into the target Git repo branch is automatically built, validated, and deployed into the Kubernetes cluster.

To create a Deploy your application to multiple clusters toolchain, click

Create toolchain

Alternatively, from the IBM Cloud console, click the Menu icon hamburger icon > Platform Automation > Toolchains. On the Toolchains page, click Create a Toolchain. On the Create a Toolchain page, click Deploy your application to multiple clusters.

Review the Welcome page

Before you start to set up your toolchain, review the prerequisites to discover what items you must first provision and configure. In the Description section, you can access an overview of the toolchain.

Welcome page
Welcome page

After you review all of this information, click Start.

Configure the toolchain name and region

  1. Review the default information for the toolchain settings. The toolchain's name identifies it in IBM Cloud. Make sure that the toolchain's name is unique within your toolchains for the same region and resource group in IBM Cloud.

    The toolchain region can differ from the cluster and registry region.

    Toolchain name and region
    Toolchain name and region

  2. To proceed to the next step to configure your toolchain, click Continue. To create the toolchain by using the current settings, click Create toolchain.

Configure the deployment source repo

The deployment source repo contains all of the deployment source code that is required to deploy the app.

  1. In the Source repository step, the default options for the deployment source repo are displayed. To view all of the available options for the underlying Source Provider, click Switch to advanced configuration. By default, the toolchain uses the sample that clones the sample deployment as an IBM-hosted Git Repos and Issue Tracking repo.

    Deployment source repo
    Deployment source repo

  2. Specify the name of the deployment source repo that you want to use. The region of the repo remains the same as the region of the toolchain.

    The toolchain template provides an IBM Cloud Satellite Config Sample application. To link an existing deployment source repo for the toolchain, click Switch to advanced configuration and specify the URL for the repo. The toolchain supports linking only to existing Git Repos and Issue Tracking repos.

By default, the deployment source repo template is cloned to your Git Repos and Issue Tracking org. To change the org, click Switch to advanced configuration and specify the repo owner.

Configure the Delivery Pipeline name

The Continuous Delivery service uses Tekton-enabled delivery pipelines.

A Delivery Pipeline automates the continuous deployment of a project. In a project's pipeline, sequences of stages retrieve input and run jobs, such as builds, tests, and deployments. Tekton resources are defined in YAML files that are managed within a code repo.

The toolchain creates a Delivery Pipeline to continuously deploy your app to multiple clusters within an IBM Cloud Satellite cluster group. You must specify a name for the Delivery Pipeline that will be displayed in your toolchain after it is created.

Delivery Pipeline name
Delivery Pipeline name

Securely store secrets

Several tools within this toolchain require secrets, such as an IBM Cloud API key. You must securely store all secrets in a secrets vault and reference them as required by the toolchain.

Using IBM Cloud, you can choose from various secrets management and data protection offerings that help you to protect your sensitive data and centralize your secret. In the Secrets step, you can specify which secret vault integrations to add or remove from your toolchain. For more information about adding and removing vault integrations, including prerequisites and by using hints, see Managing IBM Cloud secrets.

By using hints within a template, a toolchain is automatically populated with preconfigured secrets; you don't need to manually select secrets from vault integrations that are attached to the toolchain.

This tutorial uses the IBM Secrets Manager as the secrets vault.

Secrets options
Secrets options

IBM Secrets Manager securely stores and applies secrets such as API keys, Image Signature, or HashiCorp credentials that are part of your toolchain.

Secrets Manager details
Secrets Manager details

For more information about managing your secrets in IBM Key Protect or HashiCorp, see IBM Key Protect or HashiCorp.

Update the Satellite Config settings

The IBM Cloud Satellite Config tool delivers deployment configurations to specified cluster groups. The directory path of the source repo identifies which files to deploy to the provided cluster group.

Configure the target Red Hat OpenShift cluster to deploy the app to

If the API key has the required access, the following fields automatically load by using the API key that is either created, retrieved from a vault, or manually specified. If the API key is valid, values for the Branch name and Cluster group are automatically populated. You can update any of these fields to match your configuration.

  • IBM Cloud API Key: The API key that is used to interact with the ibmcloud CLI tool in several tasks. Use one of the following methods to specify the API key that you want to use:

    • Click the key icon to import an existing API key from a secret vault of your choice.
    • Copy and paste an existing API key.
    • Click New to create an API key.
    • Generate a new api-key if you don’t have an existing API key.

    You can immediately save the generated API key to an existing secrets vault of your choice.

  • Cluster namespace: Specify a name for the cluster namespace that you want to deploy the app to.

  • Branch: Specify the Git branch of your source repo.

  • Path: Specify the directory path of your source repo.

  • Cluster group: Select the IBM Cloud Satellite cluster group where you want to deploy your app.

  • Configuration name: Specify the name for the Satellite config. This name is used to create Satellite config versions that are used to create Satellite subscriptions.

IBM Cloud Satellite details
IBM Cloud Satellite Config details

Click Continue.

Complete the toolchain setup

On the Summary page, click Create toolchain. Several steps run automatically to set up your toolchain.

You can configure more toolchain integrations after the pipeline is created.

Toolchain summary
Toolchain summary

Explore your new toolchain

After you create your toolchain, each of the tool integrations that you specified during the setup are displayed.

Example toolchain
Example toolchain

Explore the Delivery Pipeline

You can explore the Delivery Pipeline to understand the toolchain flow and the different operations that run within the pipeline. The pipeline deploys build artifacts to the deployment environment. The pipeline also verifies the successful deployment of the app by running the health check.

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

  • Trigger the delivery pipeline manually.
  • Push a commit to the deployment source repo.

Run the pipeline by using a manual trigger

  1. On the Toolchain's Overview page, click the Delivery Pipeline that you want to run.

  2. Click the Run pipeline icon and then select the manual-run trigger.

    Delivery pipeline triggers
    Delivery pipeline triggers

  3. Review the trigger properties to make sure that they match your configuration.

  4. Click Run.

    Successful pipeline run
    Successful pipeline run

Verify 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 home page, click the Red Hat OpenShift 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.

Looking for help?

Get help from the IBM Cloud® Continuous Delivery development teams by joining us on Slack.

For more support options, see Getting help and support for Continuous Delivery.