Skip to content

cd-code-engine.md

Latest commit

 

History

History
268 lines (163 loc) · 19.9 KB

cd-code-engine.md

File metadata and controls

268 lines (163 loc) · 19.9 KB
copyright
years
2022, 2026
lastupdated 2026-03-30
keywords deployment strategies, toolchain, CD, automate, automation, continuous delivery, continuous integration, DevOps, IBM Cloud
subcollection ContinuousDelivery
content-type tutorial
services ContinuousDelivery
account-plan paid
completion-time 30m

{{site.data.keyword.attribute-definition-list}}

Develop and deploy an app by using Code Engine

{: #tutorial-cd-code-engine} {: toc-content-type="tutorial"} {: toc-services="ContinuousDelivery"} {: toc-account-plan="paid"} {: toc-completion-time="30m"}

{{site.data.keyword.contdelivery_short}} will be discontinued in the following regions on 10 April 2026: eu-es and jp-osa. This discontinuation also applies to any features provided within the service, including Code Risk Analyzer and {{site.data.keyword.DRA_short}}. Learn more {: important}

{{site.data.keyword.contdelivery_short}} will be discontinued in the following regions on 12 February 2027: au-syd, ca-mon, ca-tor, us-east. Code Risk Analyzer and {{site.data.keyword.DRA_short}} will also be deprecated in all regions on that date. However, if a region has no active usage of these features, the features in that region may be discontinued earlier and stop accepting new instances. Learn more {: important}

In this tutorial, you learn how to create an open toolchain by using {{site.data.keyword.contdelivery_full}} and deploy your app on {{site.data.keyword.codeengineshort}}. You also learn how toolchains are implemented in the {{site.data.keyword.contdelivery_short}} service and how to develop and deploy a simple web application (app) by using toolchains. {: shortdesc}

{{site.data.keyword.codeenginefull}} is a fully managed, serverless platform that runs your containerized workloads, including web apps, micro-services, event-driven functions, or batch jobs. {{site.data.keyword.codeengineshort}} even builds container images for you from your source code. Because these workloads are all hosted within the same Kubernetes infrastructure, all of them can seamlessly work together. The {{site.data.keyword.codeengineshort}} experience is designed so that you can focus on writing code and not on the infrastructure that is needed to host it. 

The toolchain that is used in this tutorial implements standard DevOps practices such as code scanning, acceptance tests, Git repos, and continuous integration and continuous delivery capabilities. After you create clusters and associate them with a {{site.data.keyword.contdelivery_short}} cluster group, you create a toolchain to change your app's code and push the change to the {{site.data.keyword.gitrepos}} repo. When you push changes to your repo, the Tekton-based delivery pipeline automatically builds and deploys the code.

Tekton{: external} 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 building continuous integration and continuous delivery systems. As an open source project, Tekton is managed by the Continuous Delivery Foundation{: external}. 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 {{site.data.keyword.contdelivery_short}}.

Before you begin

{: #cd-code-engine-tutorial-prereqs}

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

  • An {{site.data.keyword.cloud_notm}} account{: external}. Depending on your {{site.data.keyword.cloud_notm}} 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 {{site.data.keyword.cloud_notm}} accounts, see Setting up your {{site.data.keyword.cloud_notm}} account and Upgrading your account.

  • A Code Engine Project and an API Key. You can create these resources by using either the UI or the CLI. For more information about Code Engine Projects, see Code Engine Projects.

  • An instance of the {{site.data.keyword.contdelivery_short}} 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 {{site.data.keyword.cloud_notm}} 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

{: #code-engine-related-content} {: step}

Create the toolchain

{: #cd-codeengine-toolchain-create} {: step}

In this step, you create a Develop a Code Engine App toolchain. The target Code Engine project is configured during the toolchain setup by using your {{site.data.keyword.cloud_notm}} API key and your Code Engine project name. You can change these settings later by updating the {{site.data.keyword.deliverypipeline}} configuration. Any code that is merged into the target Git repo branch is automatically built, validated, and deployed into the Code Engine project.

To create a Develop a Code Engine App toolchain, click

Create toolchain{: external}

Alternatively, from the {{site.data.keyword.cloud_notm}} 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 Develop a Code Engine App. {: tip}

Configure the toolchain name and region

{: #codeengine-toolchain-name-region}

  1. On the Welcome screen, review the default information for the toolchain settings. The toolchain's name identifies it in {{site.data.keyword.cloud_notm}}. Make sure that the toolchain's name is unique within your toolchains for the same region and resource group in {{site.data.keyword.cloud_notm}}.

    The toolchain region can differ from the cluster and registry region. {: tip}

    Code Engine app toolchain name and region{: caption="Code Engine secure app toolchain name and region" caption-side="bottom"}

  2. Click Start.

Configure the application source code repo

{: #codeengine-tool-integration-application}

  1. In the Application step, the recommended options for the application source code repo are displayed by default. To view all of the available options for the underlying Git integration, click Advanced Options. By default, the toolchain uses the default sample that clones the sample app as an IBM-hosted {{site.data.keyword.gitrepos}} repo.

    Code Engine secure app repo{: caption="Code Engine secure app repo" caption-side="bottom"}

    You can change the name of the app repo. The region of the repo remains the same as the region of the toolchain. {: tip}

  2. Optional. The toolchain template provides a Sample Hello World Application app. If you want to link an existing Application repo for the toolchain, select Bring your own app and specify the URL for the repo. The toolchain supports linking only to existing {{site.data.keyword.gitrepos}} repos.

  3. Click Continue.

By default, the Application repo template is cloned to your {{site.data.keyword.gitrepos}} org. To change the org, enable Advanced options and specify the repo owner. {: tip}

Securely store secrets

{: #codeengine-tool-integration-secrets} {: step}

Several tools within this toolchain require secrets, such as an {{site.data.keyword.cloud_notm}} API key. You must securely store all secrets in a secrets vault and reference them as required by the toolchain.

  1. Using {{site.data.keyword.cloud_notm}}, 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 {{site.data.keyword.cloud_notm}} 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. {: tip}

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

    Code Engine secure app secrets options{: caption="Code Engine secure app secrets options" caption-side="bottom"}

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

    Code Engine Secrets Manager options{: caption="Code Engine Secrets Manager options" caption-side="bottom"}

  2. Click Continue.

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

Configure the deployment target

{: #codeengine-deployment-target} {: step}

Configure the target Code Engine project to deploy the app to. After the app passes the build, test, and scan phase, the pipeline deploys the built app image to the target Code Engine project. This deployment is now ready for acceptance testing or integration testing.

  1. 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 Container registry region and namespace Cluster region, name, namespace, and Resource group are automatically populated. You can update any of these fields to match your configuration.

    • App name: The name of the app. The default app name is the same as your toolchain name.

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

    • Container registry region: The Container Registry region in which your container namespace is located.

    • Container registry namespace: Select from the list of container namespaces in the associated Container Registry region.

    • Code Engine region: The region in which your Code Engine project is located.

    • Code Engine Resource Group: The Resource Group where your Code Engine project was created.

    • Code Engine project: The name of the project that was created in {{site.data.keyword.codeengineshort}}. Your app is deployed to this project.

    Code Engine secure app deployment target details for Rolling or Blue-Green{: caption="Code Engine secure app rolling deployment target details" caption-side="bottom"}

  2. Click Continue.

Add optional tool integrations

{: #codeengine-optional-tools} {: step}

You can add the {{site.data.keyword.DRA_full}} tool integration to your toolchain without any additional configuration.

{{site.data.keyword.DRA_short}} is included in the created toolchain. You do not need to provide any configuration steps for {{site.data.keyword.DRA_short}}. The continuous integration pipeline automatically uses the {{site.data.keyword.DRA_short}} instance that is included in the toolchain. {{site.data.keyword.DRA_short}} aggregates code, test, build, and deployment data to provide visibility into the velocity and quality of all of your teams and releases.

Click Continue.

Complete the toolchain setup

{: #code-engine-toolchain-summary} {: step}

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

You can configure the individual toolchain integrations after the pipeline is created. {: tip}

Code Engine secure app toolchain Summary{: caption="Code Engine secure app toolchain summary" caption-side="bottom"}

Explore your new toolchain

{: #cd-explore-codeengine-toolchain} {: step}

After you create your toolchain, it shows each of the tool integrations that are part of the toolchain in a diagram.

Explore the pipelines

{: #cd-code-engine-pipelines}

You can explore the pipelines to understand the toolchain flow and the different operations that run within each pipeline. The toolchain that you created contains the following pipelines:

  • Pull request pipeline: Runs when a developer merges changes from their development branch to the master branch, or to any other branch in the repo. The pull request pipeline runs the Unit Test and Static Scans on the Application Source Code.
  • Continuous integration pipeline: Runs when you merge a change into the master branch of the Application Source Code repo. The continuous integration pipeline runs the Unit Test, Code Coverage, and Static Scans on the Application Source Code, CIS check, and Bill Of Materials (BOM) check. The continuous delivery pipeline also generates the binary build artifacts and uploads them to the {{site.data.keyword.containerlong}}, as configured in the toolchain. And the continuous integration pipeline generates the metadata of the build artifacts and stores it in the Inventory repo.
  • Continuous deployment pipeline: Deploys a Code Engine component image (that the continuous integration pipeline builds and deploys) to a different Code Engine component to be hosted in a different project.

Run the pull request and continuous integration pipelines

{: #cd-pr-ci-pipelinerun}

To start the pull request pipeline, create a merge request in your app repo:

  1. On the Toolchain's Overview page, on the Repositories card, click the secure-app-toolchain-code-engine-demo app repo.
  2. From the master repo, create a branch.
  3. Update some code in the sample node app or readme file and save these changes.
  4. Submit the merge request.
  5. On the Toolchain's Overview page, on the Delivery pipelines card, click the pr-pipeline pipeline to open the pull request pipeline dashboard. The corresponding merge request in your app repo remains in the pending state until all of the stages of the pull request pipeline successfully complete.
  6. After the pull request pipeline run succeeds, you can select it to explore the completed steps.

Pull request pipeline success{: caption="Pull request pipeline success" caption-side="bottom"}

To start the continuous integration pipeline, merge the continuous integration merge request in your app repo:

  1. Go to the merge request.

  2. Merge the request so that your changes are copied to the master branch of your app repo. The continuous integration pipeline is automatically triggered.

  3. On the continuous integration Toolchain Overview page, on the Delivery pipelines card, click the ci-pipeline pipeline to open the continuous integration pipeline dashboard.

  4. After the continuous integration pipeline run succeeds, you can click the pipeline run to explore the completed steps.

    Continuous integration pipeline success{: caption="Continuous integration pipeline success" caption-side="bottom"}

  5. Expand the deploy-component task and click the execute step. Select the Logs tab, and scroll to the end of the log. Click the link to your deployed Code Engine app to view the running app.

Next steps

{: #code-engine-next-steps}

If you want to deploy the Code Engine component (that the continuous integration pipeline builds and deploys) as another component, to be hosted in another Code engine project, follow these steps:

  1. On the continuous integration Toolchain Overview page, on the Delivery pipelines card, click the cd-pipeline pipeline to open the continuous deployment pipeline dashboard.

  2. Click run pipeline to start the cd-manual-run trigger.

  3. After the continuous deployment pipeline run succeeds, you can click the pipeline run to explore the completed steps.

    Continuous deployment pipeline success{: caption="Continuous deployment pipeline success" caption-side="bottom"}

  4. Expand the deploy-component task and click the execute step. Click the Logs tab, and scroll to the end of the log. Click the link to your deployed Code Engine app to view the running app.

If you want to remove the sample app that is running on {{site.data.keyword.codeengineshort}}, follow these steps:

  1. Go to the {{site.data.keyword.codeengineshort}} Projects{: external} page.

  2. Click the project where your sample app is running.

  3. Select Applications, and then select the check box for your sample app.

  4. Click Delete.

Looking for help?

{: #cd-codeengine-tutorial-help}

{{site.data.keyword.cloud_notm}}'s AI assistant, which is powered by {{site.data.keyword.IBM_notm}}'s watsonx, is designed to help you learn about working in {{site.data.keyword.cloud_notm}} and building solutions with the catalog of available products and services. See Getting help from the AI assistant.

For more support options, see Getting help and support for {{site.data.keyword.contdelivery_short}}.