Building applications


OpenShift Container Platform 4.13

Creating and managing applications on OpenShift Container Platform

Red Hat OpenShift Documentation Team

Abstract

This document provides instructions for the various ways to create and manage instances of user-provisioned applications running on OpenShift Container Platform. This includes working with projects and provisioning applications using the Open Service Broker API.

Chapter 1. Building applications overview

Using OpenShift Container Platform, you can create, edit, delete, and manage applications using the web console or command line interface (CLI).

1.1. Working on a project

Using projects, you can organize and manage applications in isolation. You can manage the entire project lifecycle, including creating, viewing, and deleting a project in OpenShift Container Platform.

After you create the project, you can grant or revoke access to a project and manage cluster roles for the users using the Developer perspective. You can also edit the project configuration resource while creating a project template that is used for automatic provisioning of new projects.

Using the CLI, you can create a project as a different user by impersonating a request to the OpenShift Container Platform API. When you make a request to create a new project, the OpenShift Container Platform uses an endpoint to provision the project according to a customizable template. As a cluster administrator, you can choose to prevent an authenticated user group from self-provisioning new projects.

1.2. Working on an application

1.2.1. Creating an application

To create applications, you must have created a project or have access to a project with the appropriate roles and permissions. You can create an application by using either the Developer perspective in the web console, installed Operators, or the OpenShift CLI (oc). You can source the applications to be added to the project from Git, JAR files, devfiles, or the developer catalog.

You can also use components that include source or binary code, images, and templates to create an application by using the OpenShift CLI (oc). With the OpenShift Container Platform web console, you can create an application from an Operator installed by a cluster administrator.

1.2.2. Maintaining an application

After you create the application, you can use the web console to monitor your project or application metrics. You can also edit or delete the application using the web console.

When the application is running, not all applications resources are used. As a cluster administrator, you can choose to idle these scalable resources to reduce resource consumption.

1.2.3. Connecting an application to services

An application uses backing services to build and connect workloads, which vary according to the service provider. Using the Service Binding Operator, as a developer, you can bind workloads together with Operator-managed backing services, without any manual procedures to configure the binding connection. You can apply service binding also on IBM Power, IBM Z, and IBM® LinuxONE environments.

1.2.4. Deploying an application

You can deploy your application using Deployment or DeploymentConfig objects and manage them from the web console. You can create deployment strategies that help reduce downtime during a change or an upgrade to the application.

You can also use Helm, a software package manager that simplifies deployment of applications and services to OpenShift Container Platform clusters.

1.3. Using the Red Hat Marketplace

The Red Hat Marketplace is an open cloud marketplace where you can discover and access certified software for container-based environments that run on public clouds and on-premises.

Chapter 2. Projects

2.1. Working with projects

A project allows a community of users to organize and manage their content in isolation from other communities.

Note

Projects starting with openshift- and kube- are default projects. These projects host cluster components that run as pods and other infrastructure components. As such, OpenShift Container Platform does not allow you to create projects starting with openshift- or kube- using the oc new-project command. Cluster administrators can create these projects using the oc adm new-project command.

Note

You cannot assign an SCC to pods created in one of the default namespaces: default, kube-system, kube-public, openshift-node, openshift-infra, and openshift. You cannot use these namespaces for running pods or services.

2.1.1. Creating a project

You can use the OpenShift Container Platform web console or the OpenShift CLI (oc) to create a project in your cluster.

2.1.1.1. Creating a project by using the web console

You can use the OpenShift Container Platform web console to create a project in your cluster.

Note

Projects starting with openshift- and kube- are considered critical by OpenShift Container Platform. As such, OpenShift Container Platform does not allow you to create projects starting with openshift- using the web console.

Prerequisites

  • Ensure that you have the appropriate roles and permissions to create projects, applications, and other workloads in OpenShift Container Platform.

Procedure

  • If you are using the Administrator perspective:

    1. Navigate to HomeProjects.
    2. Click Create Project:

      1. In the Create Project dialog box, enter a unique name, such as myproject, in the Name field.
      2. Optional: Add the Display name and Description details for the project.
      3. Click Create.

        The dashboard for your project is displayed.

    3. Optional: Select the Details tab to view the project details.
    4. Optional: If you have adequate permissions for a project, you can use the Project Access tab to provide or revoke admin, edit, and view privileges for the project.
  • If you are using the Developer perspective:

    1. Click the Project menu and select Create Project:

      Figure 2.1. Create project

      odc create project
      1. In the Create Project dialog box, enter a unique name, such as myproject, in the Name field.
      2. Optional: Add the Display name and Description details for the project.
      3. Click Create.
    2. Optional: Use the left navigation panel to navigate to the Project view and see the dashboard for your project.
    3. Optional: In the project dashboard, select the Details tab to view the project details.
    4. Optional: If you have adequate permissions for a project, you can use the Project Access tab of the project dashboard to provide or revoke admin, edit, and view privileges for the project.
2.1.1.2. Creating a project by using the CLI

If allowed by your cluster administrator, you can create a new project.

Note

Projects starting with openshift- and kube- are considered critical by OpenShift Container Platform. As such, OpenShift Container Platform does not allow you to create Projects starting with openshift- or kube- using the oc new-project command. Cluster administrators can create these Projects using the oc adm new-project command.

Note

You cannot assign an SCC to pods created in one of the default namespaces: default, kube-system, kube-public, openshift-node, openshift-infra, and openshift. You cannot use these namespaces for running pods or services.

Procedure

  • Run:

    $ oc new-project <project_name> \
        --description="<description>" --display-name="<display_name>"

    For example:

    $ oc new-project hello-openshift \
        --description="This is an example project" \
        --display-name="Hello OpenShift"
Note

The number of projects you are allowed to create might be limited by the system administrator. After your limit is reached, you might have to delete an existing project in order to create a new one.

2.1.2. Viewing a project

You can use the OpenShift Container Platform web console or the OpenShift CLI (oc) to view a project in your cluster.

2.1.2.1. Viewing a project by using the web console

You can view the projects that you have access to by using the OpenShift Container Platform web console.

Procedure

  • If you are using the Administrator perspective:

    1. Navigate to HomeProjects in the navigation menu.
    2. Select a project to view. The Overview tab includes a dashboard for your project.
    3. Select the Details tab to view the project details.
    4. Select the YAML tab to view and update the YAML configuration for the project resource.
    5. Select the Workloads tab to see workloads in the project.
    6. Select the RoleBindings tab to view and create role bindings for your project.
  • If you are using the Developer perspective:

    1. Navigate to the Project page in the navigation menu.
    2. Select All Projects from the Project drop-down menu at the top of the screen to list all of the projects in your cluster.
    3. Select a project to view. The Overview tab includes a dashboard for your project.
    4. Select the Details tab to view the project details.
    5. If you have adequate permissions for a project, select the Project access tab view and update the privileges for the project.
2.1.2.2. Viewing a project using the CLI

When viewing projects, you are restricted to seeing only the projects you have access to view based on the authorization policy.

Procedure

  1. To view a list of projects, run:

    $ oc get projects
  2. You can change from the current project to a different project for CLI operations. The specified project is then used in all subsequent operations that manipulate project-scoped content:

    $ oc project <project_name>

2.1.3. Providing access permissions to your project using the Developer perspective

You can use the Project view in the Developer perspective to grant or revoke access permissions to your project.

Prerequisites

  • You have created a project.

Procedure

To add users to your project and provide Admin, Edit, or View access to them:

  1. In the Developer perspective, navigate to the Project page.
  2. Select your project from the Project menu.
  3. Select the Project Access tab.
  4. Click Add access to add a new row of permissions to the default ones.

    Figure 2.2. Project permissions

    odc project permissions
  5. Enter the user name, click the Select a role drop-down list, and select an appropriate role.
  6. Click Save to add the new permissions.

You can also use:

  • The Select a role drop-down list, to modify the access permissions of an existing user.
  • The Remove Access icon, to completely remove the access permissions of an existing user to the project.
Note

Advanced role-based access control is managed in the Roles and Roles Binding views in the Administrator perspective.

2.1.4. Customizing the available cluster roles using the web console

In the Developer perspective of the web console, the ProjectProject access page enables a project administrator to grant roles to users in a project. By default, the available cluster roles that can be granted to users in a project are admin, edit, and view.

As a cluster administrator, you can define which cluster roles are available in the Project access page for all projects cluster-wide. You can specify the available roles by customizing the spec.customization.projectAccess.availableClusterRoles object in the Console configuration resource.

Prerequisites

  • You have access to the cluster as a user with the cluster-admin role.

Procedure

  1. In the Administrator perspective, navigate to AdministrationCluster settings.
  2. Click the Configuration tab.
  3. From the Configuration resource list, select Console operator.openshift.io.
  4. Navigate to the YAML tab to view and edit the YAML code.
  5. In the YAML code under spec, customize the list of available cluster roles for project access. The following example specifies the default admin, edit, and view roles:

    apiVersion: operator.openshift.io/v1
    kind: Console
    metadata:
      name: cluster
    # ...
    spec:
      customization:
        projectAccess:
          availableClusterRoles:
          - admin
          - edit
          - view
  6. Click Save to save the changes to the Console configuration resource.

Verification

  1. In the Developer perspective, navigate to the Project page.
  2. Select a project from the Project menu.
  3. Select the Project access tab.
  4. Click the menu in the Role column and verify that the available roles match the configuration that you applied to the Console resource configuration.

2.1.5. Adding to a project

You can add items to your project by using the +Add page in the Developer perspective.

Prerequisites

  • You have created a project.

Procedure

  1. In the Developer perspective, navigate to the +Add page.
  2. Select your project from the Project menu.
  3. Click on an item on the +Add page and then follow the workflow.
Note

You can also use the search feature in the Add* page to find additional items to add to your project. Click * under Add at the top of the page and type the name of a component in the search field.

2.1.6. Checking the project status

You can use the OpenShift Container Platform web console or the OpenShift CLI (oc) to view the status of your project.

2.1.6.1. Checking project status by using the web console

You can review the status of your project by using the web console.

Prerequisites

  • You have created a project.

Procedure

  • If you are using the Administrator perspective:

    1. Navigate to HomeProjects.
    2. Select a project from the list.
    3. Review the project status in the Overview page.
  • If you are using the Developer perspective:

    1. Navigate to the Project page.
    2. Select a project from the Project menu.
    3. Review the project status in the Overview page.
2.1.6.2. Checking project status by using the CLI

You can review the status of your project by using the OpenShift CLI (oc).

Prerequisites

  • You have installed the OpenShift CLI (oc).
  • You have created a project.

Procedure

  1. Switch to your project:

    $ oc project <project_name> 1
    1
    Replace <project_name> with the name of your project.
  2. Obtain a high-level overview of the project:

    $ oc status

2.1.7. Deleting a project

You can use the OpenShift Container Platform web console or the OpenShift CLI (oc) to delete a project.

When you delete a project, the server updates the project status to Terminating from Active. Then, the server clears all content from a project that is in the Terminating state before finally removing the project. While a project is in Terminating status, you cannot add new content to the project. Projects can be deleted from the CLI or the web console.

2.1.7.1. Deleting a project by using the web console

You can delete a project by using the web console.

Prerequisites

  • You have created a project.
  • You have the required permissions to delete the project.

Procedure

  • If you are using the Administrator perspective:

    1. Navigate to HomeProjects.
    2. Select a project from the list.
    3. Click the Actions drop-down menu for the project and select Delete Project.

      Note

      The Delete Project option is not available if you do not have the required permissions to delete the project.

      1. In the Delete Project? pane, confirm the deletion by entering the name of your project.
      2. Click Delete.
  • If you are using the Developer perspective:

    1. Navigate to the Project page.
    2. Select the project that you want to delete from the Project menu.
    3. Click the Actions drop-down menu for the project and select Delete Project.

      Note

      If you do not have the required permissions to delete the project, the Delete Project option is not available.

      1. In the Delete Project? pane, confirm the deletion by entering the name of your project.
      2. Click Delete.
2.1.7.2. Deleting a project by using the CLI

You can delete a project by using the OpenShift CLI (oc).

Prerequisites

  • You have installed the OpenShift CLI (oc).
  • You have created a project.
  • You have the required permissions to delete the project.

Procedure

  1. Delete your project:

    $ oc delete project <project_name> 1
    1
    Replace <project_name> with the name of the project that you want to delete.

2.2. Creating a project as another user

Impersonation allows you to create a project as a different user.

2.2.1. API impersonation

You can configure a request to the OpenShift Container Platform API to act as though it originated from another user. For more information, see User impersonation in the Kubernetes documentation.

2.2.2. Impersonating a user when you create a project

You can impersonate a different user when you create a project request. Because system:authenticated:oauth is the only bootstrap group that can create project requests, you must impersonate that group.

Procedure

  • To create a project request on behalf of a different user:

    $ oc new-project <project> --as=<user> \
        --as-group=system:authenticated --as-group=system:authenticated:oauth

2.3. Configuring project creation

In OpenShift Container Platform, projects are used to group and isolate related objects. When a request is made to create a new project using the web console or oc new-project command, an endpoint in OpenShift Container Platform is used to provision the project according to a template, which can be customized.

As a cluster administrator, you can allow and configure how developers and service accounts can create, or self-provision, their own projects.

2.3.1. About project creation

The OpenShift Container Platform API server automatically provisions new projects based on the project template that is identified by the projectRequestTemplate parameter in the cluster’s project configuration resource. If the parameter is not defined, the API server creates a default template that creates a project with the requested name, and assigns the requesting user to the admin role for that project.

When a project request is submitted, the API substitutes the following parameters into the template:

Table 2.1. Default project template parameters
ParameterDescription

PROJECT_NAME

The name of the project. Required.

PROJECT_DISPLAYNAME

The display name of the project. May be empty.

PROJECT_DESCRIPTION

The description of the project. May be empty.

PROJECT_ADMIN_USER

The user name of the administrating user.

PROJECT_REQUESTING_USER

The user name of the requesting user.

Access to the API is granted to developers with the self-provisioner role and the self-provisioners cluster role binding. This role is available to all authenticated developers by default.

2.3.2. Modifying the template for new projects

As a cluster administrator, you can modify the default project template so that new projects are created using your custom requirements.

To create your own custom project template:

Procedure

  1. Log in as a user with cluster-admin privileges.
  2. Generate the default project template:

    $ oc adm create-bootstrap-project-template -o yaml > template.yaml
  3. Use a text editor to modify the generated template.yaml file by adding objects or modifying existing objects.
  4. The project template must be created in the openshift-config namespace. Load your modified template:

    $ oc create -f template.yaml -n openshift-config
  5. Edit the project configuration resource using the web console or CLI.

    • Using the web console:

      1. Navigate to the AdministrationCluster Settings page.
      2. Click Configuration to view all configuration resources.
      3. Find the entry for Project and click Edit YAML.
    • Using the CLI:

      1. Edit the project.config.openshift.io/cluster resource:

        $ oc edit project.config.openshift.io/cluster
  6. Update the spec section to include the projectRequestTemplate and name parameters, and set the name of your uploaded project template. The default name is project-request.

    Project configuration resource with custom project template

    apiVersion: config.openshift.io/v1
    kind: Project
    metadata:
    # ...
    spec:
      projectRequestTemplate:
        name: <template_name>
    # ...

  7. After you save your changes, create a new project to verify that your changes were successfully applied.

2.3.3. Disabling project self-provisioning

You can prevent an authenticated user group from self-provisioning new projects.

Procedure

  1. Log in as a user with cluster-admin privileges.
  2. View the self-provisioners cluster role binding usage by running the following command:

    $ oc describe clusterrolebinding.rbac self-provisioners

    Example output

    Name:		self-provisioners
    Labels:		<none>
    Annotations:	rbac.authorization.kubernetes.io/autoupdate=true
    Role:
      Kind:	ClusterRole
      Name:	self-provisioner
    Subjects:
      Kind	Name				Namespace
      ----	----				---------
      Group	system:authenticated:oauth

    Review the subjects in the self-provisioners section.

  3. Remove the self-provisioner cluster role from the group system:authenticated:oauth.

    • If the self-provisioners cluster role binding binds only the self-provisioner role to the system:authenticated:oauth group, run the following command:

      $ oc patch clusterrolebinding.rbac self-provisioners -p '{"subjects": null}'
    • If the self-provisioners cluster role binding binds the self-provisioner role to more users, groups, or service accounts than the system:authenticated:oauth group, run the following command:

      $ oc adm policy \
          remove-cluster-role-from-group self-provisioner \
          system:authenticated:oauth
  4. Edit the self-provisioners cluster role binding to prevent automatic updates to the role. Automatic updates reset the cluster roles to the default state.

    • To update the role binding using the CLI:

      1. Run the following command:

        $ oc edit clusterrolebinding.rbac self-provisioners
      2. In the displayed role binding, set the rbac.authorization.kubernetes.io/autoupdate parameter value to false, as shown in the following example:

        apiVersion: authorization.openshift.io/v1
        kind: ClusterRoleBinding
        metadata:
          annotations:
            rbac.authorization.kubernetes.io/autoupdate: "false"
        # ...
    • To update the role binding by using a single command:

      $ oc patch clusterrolebinding.rbac self-provisioners -p '{ "metadata": { "annotations": { "rbac.authorization.kubernetes.io/autoupdate": "false" } } }'
  5. Log in as an authenticated user and verify that it can no longer self-provision a project:

    $ oc new-project test

    Example output

    Error from server (Forbidden): You may not request a new project via this API.

    Consider customizing this project request message to provide more helpful instructions specific to your organization.

2.3.4. Customizing the project request message

When a developer or a service account that is unable to self-provision projects makes a project creation request using the web console or CLI, the following error message is returned by default:

You may not request a new project via this API.

Cluster administrators can customize this message. Consider updating it to provide further instructions on how to request a new project specific to your organization. For example:

  • To request a project, contact your system administrator at projectname@example.com.
  • To request a new project, fill out the project request form located at https://internal.example.com/openshift-project-request.

To customize the project request message:

Procedure

  1. Edit the project configuration resource using the web console or CLI.

    • Using the web console:

      1. Navigate to the AdministrationCluster Settings page.
      2. Click Configuration to view all configuration resources.
      3. Find the entry for Project and click Edit YAML.
    • Using the CLI:

      1. Log in as a user with cluster-admin privileges.
      2. Edit the project.config.openshift.io/cluster resource:

        $ oc edit project.config.openshift.io/cluster
  2. Update the spec section to include the projectRequestMessage parameter and set the value to your custom message:

    Project configuration resource with custom project request message

    apiVersion: config.openshift.io/v1
    kind: Project
    metadata:
    # ...
    spec:
      projectRequestMessage: <message_string>
    # ...

    For example:

    apiVersion: config.openshift.io/v1
    kind: Project
    metadata:
    # ...
    spec:
      projectRequestMessage: To request a project, contact your system administrator at projectname@example.com.
    # ...
  3. After you save your changes, attempt to create a new project as a developer or service account that is unable to self-provision projects to verify that your changes were successfully applied.

Chapter 3. Creating applications

3.1. Creating applications by using the Developer perspective

The Developer perspective in the web console provides you the following options from the +Add view to create applications and associated services and deploy them on OpenShift Container Platform:

  • Getting started resources: Use these resources to help you get started with Developer Console. You can choose to hide the header using the Options menu kebab .

    • Creating applications using samples: Use existing code samples to get started with creating applications on the OpenShift Container Platform.
    • Build with guided documentation: Follow the guided documentation to build applications and familiarize yourself with key concepts and terminologies.
    • Explore new developer features: Explore the new features and resources within the Developer perspective.
  • Developer catalog: Explore the Developer Catalog to select the required applications, services, or source to image builders, and then add it to your project.

    • All Services: Browse the catalog to discover services across OpenShift Container Platform.
    • Database: Select the required database service and add it to your application.
    • Operator Backed: Select and deploy the required Operator-managed service.
    • Helm chart: Select the required Helm chart to simplify deployment of applications and services.
    • Devfile: Select a devfile from the Devfile registry to declaratively define a development environment.
    • Event Source: Select an event source to register interest in a class of events from a particular system.

      Note

      The Managed services option is also available if the RHOAS Operator is installed.

  • Git repository: Import an existing codebase, Devfile, or Dockerfile from your Git repository using the From Git, From Devfile, or From Dockerfile options respectively, to build and deploy an application on OpenShift Container Platform.
  • Container images: Use existing images from an image stream or registry to deploy it on to the OpenShift Container Platform.
  • Pipelines: Use Tekton pipeline to create CI/CD pipelines for your software delivery process on the OpenShift Container Platform.
  • Serverless: Explore the Serverless options to create, build, and deploy stateless and serverless applications on the OpenShift Container Platform.

    • Channel: Create a Knative channel to create an event forwarding and persistence layer with in-memory and reliable implementations.
  • Samples: Explore the available sample applications to create, build, and deploy an application quickly.
  • Quick Starts: Explore the quick start options to create, import, and run applications with step-by-step instructions and tasks.
  • From Local Machine: Explore the From Local Machine tile to import or upload files on your local machine for building and deploying applications easily.

    • Import YAML: Upload a YAML file to create and define resources for building and deploying applications.
    • Upload JAR file: Upload a JAR file to build and deploy Java applications.
  • Share my Project: Use this option to add or remove users to a project and provide accessibility options to them.
  • Helm Chart repositories: Use this option to add Helm Chart repositories in a namespace.
  • Re-ordering of resources: Use these resources to re-order pinned resources added to your navigation pane. The drag-and-drop icon is displayed on the left side of the pinned resource when you hover over it in the navigation pane. The dragged resource can be dropped only in the section where it resides.

Note that certain options, such as Pipelines, Event Source, and Import Virtual Machines, are displayed only when the OpenShift Pipelines Operator, OpenShift Serverless Operator, and OpenShift Virtualization Operator are installed, respectively.

3.1.1. Prerequisites

To create applications using the Developer perspective ensure that:

To create serverless applications, in addition to the preceding prerequisites, ensure that:

3.1.2. Creating sample applications

You can use the sample applications in the +Add flow of the Developer perspective to create, build, and deploy applications quickly.

Prerequisites

  • You have logged in to the OpenShift Container Platform web console and are in the Developer perspective.

Procedure

  1. In the +Add view, click the Samples tile to see the Samples page.
  2. On the Samples page, select one of the available sample applications to see the Create Sample Application form.
  3. In the Create Sample Application Form:

    • In the Name field, the deployment name is displayed by default. You can modify this name as required.
    • In the Builder Image Version, a builder image is selected by default. You can modify this image version by using the Builder Image Version drop-down list.
    • A sample Git repository URL is added by default.
  4. Click Create to create the sample application. The build status of the sample application is displayed on the Topology view. After the sample application is created, you can see the deployment added to the application.

3.1.3. Creating applications by using Quick Starts

The Quick Starts page shows you how to create, import, and run applications on OpenShift Container Platform, with step-by-step instructions and tasks.

Prerequisites

  • You have logged in to the OpenShift Container Platform web console and are in the Developer perspective.

Procedure

  1. In the +Add view, click the Getting Started resourcesBuild with guided documentationView all quick starts link to view the Quick Starts page.
  2. In the Quick Starts page, click the tile for the quick start that you want to use.
  3. Click Start to begin the quick start.
  4. Perform the steps that are displayed.

3.1.4. Importing a codebase from Git to create an application

You can use the Developer perspective to create, build, and deploy an application on OpenShift Container Platform using an existing codebase in GitHub.

The following procedure walks you through the From Git option in the Developer perspective to create an application.

Procedure

  1. In the +Add view, click From Git in the Git Repository tile to see the Import from git form.
  2. In the Git section, enter the Git repository URL for the codebase you want to use to create an application. For example, enter the URL of this sample Node.js application https://github.com/sclorg/nodejs-ex. The URL is then validated.
  3. Optional: You can click Show Advanced Git Options to add details such as:

    • Git Reference to point to code in a specific branch, tag, or commit to be used to build the application.
    • Context Dir to specify the subdirectory for the application source code you want to use to build the application.
    • Source Secret to create a Secret Name with credentials for pulling your source code from a private repository.
  4. Optional: You can import a Devfile, a Dockerfile, Builder Image, or a Serverless Function through your Git repository to further customize your deployment.

    • If your Git repository contains a Devfile, a Dockerfile, a Builder Image, or a func.yaml, it is automatically detected and populated on the respective path fields.
    • If a Devfile, a Dockerfile, or a Builder Image are detected in the same repository, the Devfile is selected by default.
    • If func.yaml is detected in the Git repository, the Import Strategy changes to Serverless Function.
    • Alternatively, you can create a serverless function by clicking Create Serverless function in the +Add view using the Git repository URL.
    • To edit the file import type and select a different strategy, click Edit import strategy option.
    • If multiple Devfiles, a Dockerfiles, or a Builder Images are detected, to import a specific instance, specify the respective paths relative to the context directory.
  5. After the Git URL is validated, the recommended builder image is selected and marked with a star. If the builder image is not auto-detected, select a builder image. For the https://github.com/sclorg/nodejs-ex Git URL, by default the Node.js builder image is selected.

    1. Optional: Use the Builder Image Version drop-down to specify a version.
    2. Optional: Use the Edit import strategy to select a different strategy.
    3. Optional: For the Node.js builder image, use the Run command field to override the command to run the application.
  6. In the General section:

    1. In the Application field, enter a unique name for the application grouping, for example, myapp. Ensure that the application name is unique in a namespace.
    2. The Name field to identify the resources created for this application is automatically populated based on the Git repository URL if there are no existing applications. If there are existing applications, you can choose to deploy the component within an existing application, create a new application, or keep the component unassigned.

      Note

      The resource name must be unique in a namespace. Modify the resource name if you get an error.

  7. In the Resources section, select:

    • Deployment, to create an application in plain Kubernetes style.
    • Deployment Config, to create an OpenShift Container Platform style application.
    • Serverless Deployment, to create a Knative service.

      Note

      To set the default resource preference for importing an application, go to User PreferencesApplicationsResource type field. The Serverless Deployment option is displayed in the Import from Git form only if the OpenShift Serverless Operator is installed in your cluster. The Resources section is not available while creating a serverless function. For further details, refer to the OpenShift Serverless documentation.

  8. In the Pipelines section, select Add Pipeline, and then click Show Pipeline Visualization to see the pipeline for the application. A default pipeline is selected, but you can choose the pipeline you want from the list of available pipelines for the application.

    Note

    The Add pipeline checkbox is checked and Configure PAC is selected by default if the following criterias are fulfilled:

    • Pipeline operator is installed
    • pipelines-as-code is enabled
    • .tekton directory is detected in the Git repository
  9. Add a webhook to your repository. If Configure PAC is checked and the GitHub App is set up, you can see the Use GitHub App and Setup a webhook options. If GitHub App is not set up, you can only see the Setup a webhook option:

    1. Go to SettingsWebhooks and click Add webhook.
    2. Set the Payload URL to the Pipelines as Code controller public URL.
    3. Select the content type as application/json.
    4. Add a webhook secret and note it in an alternate location. With openssl installed on your local machine, generate a random secret.
    5. Click Let me select individual events and select these events: Commit comments, Issue comments, Pull request, and Pushes.
    6. Click Add webhook.
  10. Optional: In the Advanced Options section, the Target port and the Create a route to the application is selected by default so that you can access your application using a publicly available URL.

    If your application does not expose its data on the default public port, 80, clear the check box, and set the target port number you want to expose.

  11. Optional: You can use the following advanced options to further customize your application:

    Routing

    By clicking the Routing link, you can perform the following actions:

    • Customize the hostname for the route.
    • Specify the path the router watches.
    • Select the target port for the traffic from the drop-down list.
    • Secure your route by selecting the Secure Route check box. Select the required TLS termination type and set a policy for insecure traffic from the respective drop-down lists.

      Note

      For serverless applications, the Knative service manages all the routing options above. However, you can customize the target port for traffic, if required. If the target port is not specified, the default port of 8080 is used.

    Domain mapping

    If you are creating a Serverless Deployment, you can add a custom domain mapping to the Knative service during creation.

    • In the Advanced options section, click Show advanced Routing options.

      • If the domain mapping CR that you want to map to the service already exists, you can select it from the Domain mapping drop-down menu.
      • If you want to create a new domain mapping CR, type the domain name into the box, and select the Create option. For example, if you type in example.com, the Create option is Create "example.com".
    Health Checks

    Click the Health Checks link to add Readiness, Liveness, and Startup probes to your application. All the probes have prepopulated default data; you can add the probes with the default data or customize it as required.

    To customize the health probes:

    • Click Add Readiness Probe, if required, modify the parameters to check if the container is ready to handle requests, and select the check mark to add the probe.
    • Click Add Liveness Probe, if required, modify the parameters to check if a container is still running, and select the check mark to add the probe.
    • Click Add Startup Probe, if required, modify the parameters to check if the application within the container has started, and select the check mark to add the probe.

      For each of the probes, you can specify the request type - HTTP GET, Container Command, or TCP Socket, from the drop-down list. The form changes as per the selected request type. You can then modify the default values for the other parameters, such as the success and failure thresholds for the probe, number of seconds before performing the first probe after the container starts, frequency of the probe, and the timeout value.

    Build Configuration and Deployment

    Click the Build Configuration and Deployment links to see the respective configuration options. Some options are selected by default; you can customize them further by adding the necessary triggers and environment variables.

    For serverless applications, the Deployment option is not displayed as the Knative configuration resource maintains the desired state for your deployment instead of a DeploymentConfig resource.

    Scaling

    Click the Scaling link to define the number of pods or instances of the application you want to deploy initially.

    If you are creating a serverless deployment, you can also configure the following settings:

    • Min Pods determines the lower limit for the number of pods that must be running at any given time for a Knative service. This is also known as the minScale setting.
    • Max Pods determines the upper limit for the number of pods that can be running at any given time for a Knative service. This is also known as the maxScale setting.
    • Concurrency target determines the number of concurrent requests desired for each instance of the application at a given time.
    • Concurrency limit determines the limit for the number of concurrent requests allowed for each instance of the application at a given time.
    • Concurrency utilization determines the percentage of the concurrent requests limit that must be met before Knative scales up additional pods to handle additional traffic.
    • Autoscale window defines the time window over which metrics are averaged to provide input for scaling decisions when the autoscaler is not in panic mode. A service is scaled-to-zero if no requests are received during this window. The default duration for the autoscale window is 60s. This is also known as the stable window.
    Resource Limit
    Click the Resource Limit link to set the amount of CPU and Memory resources a container is guaranteed or allowed to use when running.
    Labels
    Click the Labels link to add custom labels to your application.
  12. Click Create to create the application and a success notification is displayed. You can see the build status of the application in the Topology view.

3.1.5. Deploying a Java application by uploading a JAR file

You can use the web console Developer perspective to upload a JAR file by using the following options:

  • Navigate to the +Add view of the Developer perspective, and click Upload JAR file in the From Local Machine tile. Browse and select your JAR file, or drag a JAR file to deploy your application.
  • Navigate to the Topology view and use the Upload JAR file option, or drag a JAR file to deploy your application.
  • Use the in-context menu in the Topology view, and then use the Upload JAR file option to upload your JAR file to deploy your application.

Prerequisites

  • The Cluster Samples Operator must be installed by a cluster administrator.
  • You have access to the OpenShift Container Platform web console and are in the Developer perspective.

Procedure

  1. In the Topology view, right-click anywhere to view the Add to Project menu.
  2. Hover over the Add to Project menu to see the menu options, and then select the Upload JAR file option to see the Upload JAR file form. Alternatively, you can drag the JAR file into the Topology view.
  3. In the JAR file field, browse for the required JAR file on your local machine and upload it. Alternatively, you can drag the JAR file on to the field. A toast alert is displayed at the top right if an incompatible file type is dragged into the Topology view. A field error is displayed if an incompatible file type is dropped on the field in the upload form.
  4. The runtime icon and builder image are selected by default. If a builder image is not auto-detected, select a builder image. If required, you can change the version using the Builder Image Version drop-down list.
  5. Optional: In the Application Name field, enter a unique name for your application to use for resource labelling.
  6. In the Name field, enter a unique component name for the associated resources.
  7. Optional: Using the Advanced optionsResource type drop-down list, select a different resource type from the list of default resource types.
  8. In the Advanced options menu, click Create a Route to the Application to configure a public URL for your deployed application.
  9. Click Create to deploy the application. A toast notification is shown to notify you that the JAR file is being uploaded. The toast notification also includes a link to view the build logs.
Note

If you attempt to close the browser tab while the build is running, a web alert is displayed.

After the JAR file is uploaded and the application is deployed, you can view the application in the Topology view.

3.1.6. Using the Devfile registry to access devfiles

You can use the devfiles in the +Add flow of the Developer perspective to create an application. The +Add flow provides a complete integration with the devfile community registry. A devfile is a portable YAML file that describes your development environment without needing to configure it from scratch. Using the Devfile registry, you can use a preconfigured devfile to create an application.

Procedure

  1. Navigate to Developer Perspective+AddDeveloper CatalogAll Services. A list of all the available services in the Developer Catalog is displayed.
  2. Under Type, click Devfiles to browse for devfiles that support a particular language or framework. Alternatively, you can use the keyword filter to search for a particular devfile using their name, tag, or description.
  3. Click the devfile you want to use to create an application. The devfile tile displays the details of the devfile, including the name, description, provider, and the documentation of the devfile.
  4. Click Create to create an application and view the application in the Topology view.

3.1.7. Using the Developer Catalog to add services or components to your application

You use the Developer Catalog to deploy applications and services based on Operator backed services such as Databases, Builder Images, and Helm Charts. The Developer Catalog contains a collection of application components, services, event sources, or source-to-image builders that you can add to your project. Cluster administrators can customize the content made available in the catalog.

Procedure

  1. In the Developer perspective, navigate to the +Add view and from the Developer Catalog tile, click All Services to view all the available services in the Developer Catalog.
  2. Under All Services, select the kind of service or the component you need to add to your project. For this example, select Databases to list all the database services and then click MariaDB to see the details for the service.
  3. Click Instantiate Template to see an automatically populated template with details for the MariaDB service, and then click Create to create and view the MariaDB service in the Topology view.

    Figure 3.1. MariaDB in Topology

    odc devcatalog toplogy

3.1.8. Additional resources

3.2. Creating applications from installed Operators

Operators are a method of packaging, deploying, and managing a Kubernetes application. You can create applications on OpenShift Container Platform using Operators that have been installed by a cluster administrator.

This guide walks developers through an example of creating applications from an installed Operator using the OpenShift Container Platform web console.

Additional resources

  • See the Operators guide for more on how Operators work and how the Operator Lifecycle Manager is integrated in OpenShift Container Platform.

3.2.1. Creating an etcd cluster using an Operator

This procedure walks through creating a new etcd cluster using the etcd Operator, managed by Operator Lifecycle Manager (OLM).

Prerequisites

  • Access to an OpenShift Container Platform 4.13 cluster.
  • The etcd Operator already installed cluster-wide by an administrator.

Procedure

  1. Create a new project in the OpenShift Container Platform web console for this procedure. This example uses a project called my-etcd.
  2. Navigate to the Operators → Installed Operators page. The Operators that have been installed to the cluster by the cluster administrator and are available for use are shown here as a list of cluster service versions (CSVs). CSVs are used to launch and manage the software provided by the Operator.

    Tip

    You can get this list from the CLI using:

    $ oc get csv
  3. On the Installed Operators page, click the etcd Operator to view more details and available actions.

    As shown under Provided APIs, this Operator makes available three new resource types, including one for an etcd Cluster (the EtcdCluster resource). These objects work similar to the built-in native Kubernetes ones, such as Deployment or ReplicaSet, but contain logic specific to managing etcd.

  4. Create a new etcd cluster:

    1. In the etcd Cluster API box, click Create instance.
    2. The next page allows you to make any modifications to the minimal starting template of an EtcdCluster object, such as the size of the cluster. For now, click Create to finalize. This triggers the Operator to start up the pods, services, and other components of the new etcd cluster.
  5. Click the example etcd cluster, then click the Resources tab to see that your project now contains a number of resources created and configured automatically by the Operator.

    Verify that a Kubernetes service has been created that allows you to access the database from other pods in your project.

  6. All users with the edit role in a given project can create, manage, and delete application instances (an etcd cluster, in this example) managed by Operators that have already been created in the project, in a self-service manner, just like a cloud service. If you want to enable additional users with this ability, project administrators can add the role using the following command:

    $ oc policy add-role-to-user edit <user> -n <target_project>

You now have an etcd cluster that will react to failures and rebalance data as pods become unhealthy or are migrated between nodes in the cluster. Most importantly, cluster administrators or developers with proper access can now easily use the database with their applications.

3.3. Creating applications by using the CLI

You can create an OpenShift Container Platform application from components that include source or binary code, images, and templates by using the OpenShift Container Platform CLI.

The set of objects created by new-app depends on the artifacts passed as input: source repositories, images, or templates.

3.3.1. Creating an application from source code

With the new-app command you can create applications from source code in a local or remote Git repository.

The new-app command creates a build configuration, which itself creates a new application image from your source code. The new-app command typically also creates a Deployment object to deploy the new image, and a service to provide load-balanced access to the deployment running your image.

OpenShift Container Platform automatically detects whether the pipeline, source, or docker build strategy should be used, and in the case of source build, detects an appropriate language builder image.

3.3.1.1. Local

To create an application from a Git repository in a local directory:

$ oc new-app /<path to source code>
Note

If you use a local Git repository, the repository must have a remote named origin that points to a URL that is accessible by the OpenShift Container Platform cluster. If there is no recognized remote, running the new-app command will create a binary build.

3.3.1.2. Remote

To create an application from a remote Git repository:

$ oc new-app https://github.com/sclorg/cakephp-ex

To create an application from a private remote Git repository:

$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret
Note

If you use a private remote Git repository, you can use the --source-secret flag to specify an existing source clone secret that will get injected into your build config to access the repository.

You can use a subdirectory of your source code repository by specifying a --context-dir flag. To create an application from a remote Git repository and a context subdirectory:

$ oc new-app https://github.com/sclorg/s2i-ruby-container.git \
    --context-dir=2.0/test/puma-test-app

Also, when specifying a remote URL, you can specify a Git branch to use by appending #<branch_name> to the end of the URL:

$ oc new-app https://github.com/openshift/ruby-hello-world.git#beta4
3.3.1.3. Build strategy detection

OpenShift Container Platform automatically determines which build strategy to use by detecting certain files:

  • If a Jenkins file exists in the root or specified context directory of the source repository when creating a new application, OpenShift Container Platform generates a pipeline build strategy.

    Note

    The pipeline build strategy is deprecated; consider using Red Hat OpenShift Pipelines instead.

  • If a Dockerfile exists in the root or specified context directory of the source repository when creating a new application, OpenShift Container Platform generates a docker build strategy.
  • If neither a Jenkins file nor a Dockerfile is detected, OpenShift Container Platform generates a source build strategy.

Override the automatically detected build strategy by setting the --strategy flag to docker, pipeline, or source.

$ oc new-app /home/user/code/myapp --strategy=docker
Note

The oc command requires that files containing build sources are available in a remote Git repository. For all source builds, you must use git remote -v.

3.3.1.4. Language detection

If you use the source build strategy, new-app attempts to determine the language builder to use by the presence of certain files in the root or specified context directory of the repository:

Table 3.1. Languages detected by new-app
LanguageFiles

dotnet

project.json, *.csproj

jee

pom.xml

nodejs

app.json, package.json

perl

cpanfile, index.pl

php

composer.json, index.php

python

requirements.txt, setup.py

ruby

Gemfile, Rakefile, config.ru

scala

build.sbt

golang

Godeps, main.go

After a language is detected, new-app searches the OpenShift Container Platform server for image stream tags that have a supports annotation matching the detected language, or an image stream that matches the name of the detected language. If a match is not found, new-app searches the Docker Hub registry for an image that matches the detected language based on name.

You can override the image the builder uses for a particular source repository by specifying the image, either an image stream or container specification, and the repository with a ~ as a separator. Note that if this is done, build strategy detection and language detection are not carried out.

For example, to use the myproject/my-ruby imagestream with the source in a remote repository:

$ oc new-app myproject/my-ruby~https://github.com/openshift/ruby-hello-world.git

To use the openshift/ruby-20-centos7:latest container image stream with the source in a local repository:

$ oc new-app openshift/ruby-20-centos7:latest~/home/user/code/my-ruby-app
Note

Language detection requires the Git client to be locally installed so that your repository can be cloned and inspected. If Git is not available, you can avoid the language detection step by specifying the builder image to use with your repository with the <image>~<repository> syntax.

The -i <image> <repository> invocation requires that new-app attempt to clone repository to determine what type of artifact it is, so this will fail if Git is not available.

The -i <image> --code <repository> invocation requires new-app clone repository to determine whether image should be used as a builder for the source code, or deployed separately, as in the case of a database image.

3.3.2. Creating an application from an image

You can deploy an application from an existing image. Images can come from image streams in the OpenShift Container Platform server, images in a specific registry, or images in the local Docker server.

The new-app command attempts to determine the type of image specified in the arguments passed to it. However, you can explicitly tell new-app whether the image is a container image using the --docker-image argument or an image stream using the -i|--image-stream argument.

Note

If you specify an image from your local Docker repository, you must ensure that the same image is available to the OpenShift Container Platform cluster nodes.

3.3.2.1. Docker Hub MySQL image

Create an application from the Docker Hub MySQL image, for example:

$ oc new-app mysql
3.3.2.2. Image in a private registry

Create an application using an image in a private registry, specify the full container image specification:

$ oc new-app myregistry:5000/example/myimage
3.3.2.3. Existing image stream and optional image stream tag

Create an application from an existing image stream and optional image stream tag:

$ oc new-app my-stream:v1

3.3.3. Creating an application from a template

You can create an application from a previously stored template or from a template file, by specifying the name of the template as an argument. For example, you can store a sample application template and use it to create an application.

Upload an application template to your current project’s template library. The following example uploads an application template from a file called examples/sample-app/application-template-stibuild.json:

$ oc create -f examples/sample-app/application-template-stibuild.json

Then create a new application by referencing the application template. In this example, the template name is ruby-helloworld-sample:

$ oc new-app ruby-helloworld-sample

To create a new application by referencing a template file in your local file system, without first storing it in OpenShift Container Platform, use the -f|--file argument. For example:

$ oc new-app -f examples/sample-app/application-template-stibuild.json
3.3.3.1. Template parameters

When creating an application based on a template, use the -p|--param argument to set parameter values that are defined by the template:

$ oc new-app ruby-helloworld-sample \
    -p ADMIN_USERNAME=admin -p ADMIN_PASSWORD=mypassword

You can store your parameters in a file, then use that file with --param-file when instantiating a template. If you want to read the parameters from standard input, use --param-file=-. The following is an example file called helloworld.params:

ADMIN_USERNAME=admin
ADMIN_PASSWORD=mypassword

Reference the parameters in the file when instantiating a template:

$ oc new-app ruby-helloworld-sample --param-file=helloworld.params

3.3.4. Modifying application creation

The new-app command generates OpenShift Container Platform objects that build, deploy, and run the application that is created. Normally, these objects are created in the current project and assigned names that are derived from the input source repositories or the input images. However, with new-app you can modify this behavior.

Table 3.2. new-app output objects
ObjectDescription

BuildConfig

A BuildConfig object is created for each source repository that is specified in the command line. The BuildConfig object specifies the strategy to use, the source location, and the build output location.

ImageStreams

For the BuildConfig object, two image streams are usually created. One represents the input image. With source builds, this is the builder image. With Docker builds, this is the FROM image. The second one represents the output image. If a container image was specified as input to new-app, then an image stream is created for that image as well.

DeploymentConfig

A DeploymentConfig object is created either to deploy the output of a build, or a specified image. The new-app command creates emptyDir volumes for all Docker volumes that are specified in containers included in the resulting DeploymentConfig object .

Service

The new-app command attempts to detect exposed ports in input images. It uses the lowest numeric exposed port to generate a service that exposes that port. To expose a different port, after new-app has completed, simply use the oc expose command to generate additional services.

Other

Other objects can be generated when instantiating templates, according to the template.

3.3.4.1. Specifying environment variables

When generating applications from a template, source, or an image, you can use the -e|--env argument to pass environment variables to the application container at run time:

$ oc new-app openshift/postgresql-92-centos7 \
    -e POSTGRESQL_USER=user \
    -e POSTGRESQL_DATABASE=db \
    -e POSTGRESQL_PASSWORD=password

The variables can also be read from file using the --env-file argument. The following is an example file called postgresql.env:

POSTGRESQL_USER=user
POSTGRESQL_DATABASE=db
POSTGRESQL_PASSWORD=password

Read the variables from the file:

$ oc new-app openshift/postgresql-92-centos7 --env-file=postgresql.env

Additionally, environment variables can be given on standard input by using --env-file=-:

$ cat postgresql.env | oc new-app openshift/postgresql-92-centos7 --env-file=-
Note

Any BuildConfig objects created as part of new-app processing are not updated with environment variables passed with the -e|--env or --env-file argument.

3.3.4.2. Specifying build environment variables

When generating applications from a template, source, or an image, you can use the --build-env argument to pass environment variables to the build container at run time:

$ oc new-app openshift/ruby-23-centos7 \
    --build-env HTTP_PROXY=http://myproxy.net:1337/ \
    --build-env GEM_HOME=~/.gem

The variables can also be read from a file using the --build-env-file argument. The following is an example file called ruby.env:

HTTP_PROXY=http://myproxy.net:1337/
GEM_HOME=~/.gem

Read the variables from the file:

$ oc new-app openshift/ruby-23-centos7 --build-env-file=ruby.env

Additionally, environment variables can be given on standard input by using --build-env-file=-:

$ cat ruby.env | oc new-app openshift/ruby-23-centos7 --build-env-file=-
3.3.4.3. Specifying labels

When generating applications from source, images, or templates, you can use the -l|--label argument to add labels to the created objects. Labels make it easy to collectively select, configure, and delete objects associated with the application.

$ oc new-app https://github.com/openshift/ruby-hello-world -l name=hello-world
3.3.4.4. Viewing the output without creation

To see a dry-run of running the new-app command, you can use the -o|--output argument with a yaml or json value. You can then use the output to preview the objects that are created or redirect it to a file that you can edit. After you are satisfied, you can use oc create to create the OpenShift Container Platform objects.

To output new-app artifacts to a file, run the following:

$ oc new-app https://github.com/openshift/ruby-hello-world \
    -o yaml > myapp.yaml

Edit the file:

$ vi myapp.yaml

Create a new application by referencing the file:

$ oc create -f myapp.yaml
3.3.4.5. Creating objects with different names

Objects created by new-app are normally named after the source repository, or the image used to generate them. You can set the name of the objects produced by adding a --name flag to the command:

$ oc new-app https://github.com/openshift/ruby-hello-world --name=myapp
3.3.4.6. Creating objects in a different project

Normally, new-app creates objects in the current project. However, you can create objects in a different project by using the -n|--namespace argument:

$ oc new-app https://github.com/openshift/ruby-hello-world -n myproject
3.3.4.7. Creating multiple objects

The new-app command allows creating multiple applications specifying multiple parameters to new-app. Labels specified in the command line apply to all objects created by the single command. Environment variables apply to all components created from source or images.

To create an application from a source repository and a Docker Hub image:

$ oc new-app https://github.com/openshift/ruby-hello-world mysql
Note

If a source code repository and a builder image are specified as separate arguments, new-app uses the builder image as the builder for the source code repository. If this is not the intent, specify the required builder image for the source using the ~ separator.

3.3.4.8. Grouping images and source in a single pod

The new-app command allows deploying multiple images together in a single pod. To specify which images to group together, use the + separator. The --group command line argument can also be used to specify the images that should be grouped together. To group the image built from a source repository with other images, specify its builder image in the group:

$ oc new-app ruby+mysql

To deploy an image built from source and an external image together:

$ oc new-app \
    ruby~https://github.com/openshift/ruby-hello-world \
    mysql \
    --group=ruby+mysql
3.3.4.9. Searching for images, templates, and other inputs

To search for images, templates, and other inputs for the oc new-app command, add the --search and --list flags. For example, to find all of the images or templates that include PHP:

$ oc new-app --search php

Chapter 4. Viewing application composition by using the Topology view

The Topology view in the Developer perspective of the web console provides a visual representation of all the applications within a project, their build status, and the components and services associated with them.

4.1. Prerequisites

To view your applications in the Topology view and interact with them, ensure that:

4.2. Viewing the topology of your application

You can navigate to the Topology view using the left navigation panel in the Developer perspective. After you deploy an application, you are directed automatically to the Graph view where you can see the status of the application pods, quickly access the application on a public URL, access the source code to modify it, and see the status of your last build. You can zoom in and out to see more details for a particular application.

The Topology view provides you the option to monitor your applications using the List view. Use the List view icon ( odc list view icon ) to see a list of all your applications and use the Graph view icon ( odc topology view icon ) to switch back to the graph view.

You can customize the views as required using the following:

  • Use the Find by name field to find the required components. Search results may appear outside of the visible area; click Fit to Screen from the lower-left toolbar to resize the Topology view to show all components.
  • Use the Display Options drop-down list to configure the Topology view of the various application groupings. The options are available depending on the types of components deployed in the project:

    • Expand group

      • Virtual Machines: Toggle to show or hide the virtual machines.
      • Application Groupings: Clear to condense the application groups into cards with an overview of an application group and alerts associated with it.
      • Helm Releases: Clear to condense the components deployed as Helm Release into cards with an overview of a given release.
      • Knative Services: Clear to condense the Knative Service components into cards with an overview of a given component.
      • Operator Groupings: Clear to condense the components deployed with an Operator into cards with an overview of the given group.
    • Show elements based on Pod Count or Labels

      • Pod Count: Select to show the number of pods of a component in the component icon.
      • Labels: Toggle to show or hide the component labels.

The Topology view also provides you the Export application option to download your application in the ZIP file format. You can then import the downloaded application to another project or cluster. For more details, see Exporting an application to another project or cluster in the Additional resources section.

4.3. Interacting with applications and components

In the Topology view in the Developer perspective of the web console, the Graph view provides the following options to interact with applications and components:

  • Click Open URL ( odc open url ) to see your application exposed by the route on a public URL.
  • Click Edit Source code to access your source code and modify it.

    Note

    This feature is available only when you create applications using the From Git, From Catalog, and the From Dockerfile options.

  • Hover your cursor over the lower left icon on the pod to see the name of the latest build and its status. The status of the application build is indicated as New ( odc build new ), Pending ( odc build pending ), Running ( odc build running ), Completed ( odc build completed ), Failed ( odc build failed ), and Canceled ( odc build canceled ).
  • The status or phase of the pod is indicated by different colors and tooltips as:

    • Running ( odc pod running ): The pod is bound to a node and all of the containers are created. At least one container is still running or is in the process of starting or restarting.
    • Not Ready ( odc pod not ready ): The pods which are running multiple containers, not all containers are ready.
    • Warning( odc pod warning ): Containers in pods are being terminated, however termination did not succeed. Some containers may be other states.
    • Failed( odc pod failed ): All containers in the pod terminated but least one container has terminated in failure. That is, the container either exited with non-zero status or was terminated by the system.
    • Pending( odc pod pending ): The pod is accepted by the Kubernetes cluster, but one or more of the containers has not been set up and made ready to run. This includes time a pod spends waiting to be scheduled as well as the time spent downloading container images over the network.
    • Succeeded( odc pod succeeded ): All containers in the pod terminated successfully and will not be restarted.
    • Terminating( odc pod terminating ): When a pod is being deleted, it is shown as Terminating by some kubectl commands. Terminating status is not one of the pod phases. A pod is granted a graceful termination period, which defaults to 30 seconds.
    • Unknown( odc pod unknown ): The state of the pod could not be obtained. This phase typically occurs due to an error in communicating with the node where the pod should be running.
  • After you create an application and an image is deployed, the status is shown as Pending. After the application is built, it is displayed as Running.

    Figure 4.1. Application topology

    odc application topology

    The application resource name is appended with indicators for the different types of resource objects as follows:

    • CJ: CronJob
    • D: Deployment
    • DC: DeploymentConfig
    • DS: DaemonSet
    • J: Job
    • P: Pod
    • SS: StatefulSet
    • odc serverless app (Knative): A serverless application

      Note

      Serverless applications take some time to load and display on the Graph view. When you deploy a serverless application, it first creates a service resource and then a revision. After that, it is deployed and displayed on the Graph view. If it is the only workload, you might be redirected to the Add page. After the revision is deployed, the serverless application is displayed on the Graph view.

4.4. Scaling application pods and checking builds and routes

The Topology view provides the details of the deployed components in the Overview panel. You can use the Overview and Details tabs to scale the application pods, check build status, services, and routes as follows:

  • Click on the component node to see the Overview panel to the right. Use the Details tab to:

    • Scale your pods using the up and down arrows to increase or decrease the number of instances of the application manually. For serverless applications, the pods are automatically scaled down to zero when idle and scaled up depending on the channel traffic.
    • Check the Labels, Annotations, and Status of the application.
  • Click the Resources tab to:

    • See the list of all the pods, view their status, access logs, and click on the pod to see the pod details.
    • See the builds, their status, access logs, and start a new build if needed.
    • See the services and routes used by the component.

    For serverless applications, the Resources tab provides information on the revision, routes, and the configurations used for that component.

4.5. Adding components to an existing project

You can add components to a project.

Procedure

  1. Navigate to the +Add view.
  2. Click Add to Project ( odc add to project ) next to left navigation pane or press Ctrl+Space
  3. Search for the component and click the Start/Create/Install button or click Enter to add the component to the project and see it in the topology Graph view.

    Figure 4.2. Adding component via quick search

    odc quick search

Alternatively, you can also use the available options in the context menu, such as Import from Git, Container Image, Database, From Catalog, Operator Backed, Helm Charts, Samples, or Upload JAR file, by right-clicking in the topology Graph view to add a component to your project.

Figure 4.3. Context menu to add services

odc context project

4.6. Grouping multiple components within an application

You can use the +Add view to add multiple components or services to your project and use the topology Graph view to group applications and resources within an application group.

Prerequisites

  • You have created and deployed minimum two or more components on OpenShift Container Platform using the Developer perspective.

Procedure

  • To add a service to the existing application group, press Shift+ drag it to the existing application group. Dragging a component and adding it to an application group adds the required labels to the component.

    Figure 4.4. Application grouping

    odc app grouping label

Alternatively, you can also add the component to an application as follows:

  1. Click the service pod to see the Overview panel to the right.
  2. Click the Actions drop-down menu and select Edit Application Grouping.
  3. In the Edit Application Grouping dialog box, click the Application drop-down list, and select an appropriate application group.
  4. Click Save to add the service to the application group.

You can remove a component from an application group by selecting the component and using Shift+ drag to drag it out of the application group.

4.7. Adding services to your application

To add a service to your application use the +Add actions using the context menu in the topology Graph view.

Note

In addition to the context menu, you can add services by using the sidebar or hovering and dragging the dangling arrow from the application group.

Procedure

  1. Right-click an application group in the topology Graph view to display the context menu.

    Figure 4.5. Add resource context menu

    odc context menu
  2. Use Add to Application to select a method for adding a service to the application group, such as From Git, Container Image, From Dockerfile, From Devfile, Upload JAR file, Event Source, Channel, or Broker.
  3. Complete the form for the method you choose and click Create. For example, to add a service based on the source code in your Git repository, choose the From Git method, fill in the Import from Git form, and click Create.

4.8. Removing services from your application

In the topology Graph view remove a service from your application using the context menu.

Procedure

  1. Right-click on a service in an application group in the topology Graph view to display the context menu.
  2. Select Delete Deployment to delete the service.

    Figure 4.6. Deleting deployment option

    odc deleting deployment

4.9. Labels and annotations used for the Topology view

The Topology view uses the following labels and annotations:

Icon displayed in the node
Icons in the node are defined by looking for matching icons using the app.openshift.io/runtime label, followed by the app.kubernetes.io/name label. This matching is done using a predefined set of icons.
Link to the source code editor or the source
The app.openshift.io/vcs-uri annotation is used to create links to the source code editor.
Node Connector
The app.openshift.io/connects-to annotation is used to connect the nodes.
App grouping
The app.kubernetes.io/part-of=<appname> label is used to group the applications, services, and components.

For detailed information on the labels and annotations OpenShift Container Platform applications must use, see Guidelines for labels and annotations for OpenShift applications.

4.10. Additional resources

Chapter 5. Exporting applications

As a developer, you can export your application in the ZIP file format. Based on your needs, import the exported application to another project in the same cluster or a different cluster by using the Import YAML option in the +Add view. Exporting your application helps you to reuse your application resources and saves your time.

5.1. Prerequisites

  • You have installed the gitops-primer Operator from the OperatorHub.

    Note

    The Export application option is disabled in the Topology view even after installing the gitops-primer Operator.

  • You have created an application in the Topology view to enable Export application.

5.2. Procedure

  1. In the developer perspective, perform one of the following steps:

    1. Navigate to the +Add view and click Export application in the Application portability tile.
    2. Navigate to the Topology view and click Export application.
  2. Click OK in the Export Application dialog box. A notification opens to confirm that the export of resources from your project has started.
  3. Optional steps that you might need to perform in the following scenarios:

    • If you have started exporting an incorrect application, click Export applicationCancel Export.
    • If your export is already in progress and you want to start a fresh export, click Export applicationRestart Export.
    • If you want to view logs associated with exporting an application, click Export application and the View Logs link.

      export application dialog box
  4. After a successful export, click Download in the dialog box to download application resources in ZIP format onto your machine.

Chapter 6. Connecting applications to services

6.1. Release notes for Service Binding Operator

The Service Binding Operator consists of a controller and an accompanying custom resource definition (CRD) for service binding. It manages the data plane for workloads and backing services. The Service Binding Controller reads the data made available by the control plane of backing services. Then, it projects this data to workloads according to the rules specified through the ServiceBinding resource.

With Service Binding Operator, you can:

  • Bind your workloads together with Operator-managed backing services.
  • Automate configuration of binding data.
  • Provide service operators a low-touch administrative experience to provision and manage access to services.
  • Enrich development lifecycle with a consistent and declarative service binding method that eliminates discrepancies in cluster environments.

The custom resource definition (CRD) of the Service Binding Operator supports the following APIs:

  • Service Binding with the binding.operators.coreos.com API group.
  • Service Binding (Spec API) with the servicebinding.io API group.

6.1.1. Support matrix

Some features in the following table are in Technology Preview. These experimental features are not intended for production use.

In the table, features are marked with the following statuses:

  • TP: Technology Preview
  • GA: General Availability

Note the following scope of support on the Red Hat Customer Portal for these features:

Table 6.1. Support matrix
Service Binding OperatorAPI Group and Support StatusOpenShift Versions

Version

binding.operators.coreos.com

servicebinding.io

 

1.3.3

GA

GA

4.9-4.12

1.3.1

GA

GA

4.9-4.11

1.3

GA

GA

4.9-4.11

1.2

GA

GA

4.7-4.11

1.1.1

GA

TP

4.7-4.10

1.1

GA

TP

4.7-4.10

1.0.1

GA

TP

4.7-4.9

1.0

GA

TP

4.7-4.9

6.1.2. Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see Red Hat CTO Chris Wright’s message.

6.1.3. Release notes for Service Binding Operator 1.3.3

Service Binding Operator 1.3.3 is now available on OpenShift Container Platform 4.9, 4.10, 4.11 and 4.12.

6.1.3.1. Fixed issues
  • Before this update, a security vulnerability CVE-2022-41717 was noted for Service Binding Operator. This update fixes the CVE-2022-41717 error and updates the golang.org/x/net package from v0.0.0-20220906165146-f3363e06e74c to v0.4.0. APPSVC-1256
  • Before this update, Provisioned Services were only detected if the respective resource had the "servicebinding.io/provisioned-service: true" annotation set while other Provisioned Services were missed. With this update, the detection mechanism identifies all Provisioned Services correctly based on the "status.binding.name" attribute. APPSVC-1204

6.1.4. Release notes for Service Binding Operator 1.3.1

Service Binding Operator 1.3.1 is now available on OpenShift Container Platform 4.9, 4.10, and 4.11.

6.1.4.1. Fixed issues
  • Before this update, a security vulnerability CVE-2022-32149 was noted for Service Binding Operator. This update fixes the CVE-2022-32149 error and updates the golang.org/x/text package from v0.3.7 to v0.3.8. APPSVC-1220

6.1.5. Release notes for Service Binding Operator 1.3

Service Binding Operator 1.3 is now available on OpenShift Container Platform 4.9, 4.10, and 4.11.

6.1.5.1. Removed functionality
  • In Service Binding Operator 1.3, the Operator Lifecycle Manager (OLM) descriptor feature has been removed to improve resource utilization. As an alternative to OLM descriptors, you can use CRD annotations to declare binding data.

6.1.6. Release notes for Service Binding Operator 1.2

Service Binding Operator 1.2 is now available on OpenShift Container Platform 4.7, 4.8, 4.9, 4.10, and 4.11.

6.1.6.1. New features

This section highlights what is new in Service Binding Operator 1.2:

  • Enable Service Binding Operator to consider optional fields in the annotations by setting the optional flag value to true.
  • Support for servicebinding.io/v1beta1 resources.
  • Improvements to the discoverability of bindable services by exposing the relevant binding secret without requiring a workload to be present.
6.1.6.2. Known issues
  • Currently, when you install Service Binding Operator on OpenShift Container Platform 4.11, the memory footprint of Service Binding Operator increases beyond expected limits. With low usage, however, the memory footprint stays within the expected ranges of your environment or scenarios. In comparison with OpenShift Container Platform 4.10, under stress, both the average and maximum memory footprint increase considerably. This issue is evident in the previous versions of Service Binding Operator as well. There is currently no workaround for this issue. APPSVC-1200
  • By default, the projected files get their permissions set to 0644. Service Binding Operator cannot set specific permissions due to a bug in Kubernetes that causes issues if the service expects specific permissions such as, 0600. As a workaround, you can modify the code of the program or the application that is running inside a workload resource to copy the file to the /tmp directory and set the appropriate permissions. APPSVC-1127
  • There is currently a known issue with installing Service Binding Operator in a single namespace installation mode. The absence of an appropriate namespace-scoped role-based access control (RBAC) rule prevents the successful binding of an application to a few known Operator-backed services that the Service Binding Operator can automatically detect and bind to. When this happens, it generates an error message similar to the following example:

    Example error message

    `postgresclusters.postgres-operator.crunchydata.com "hippo" is forbidden:
            User "system:serviceaccount:my-petclinic:service-binding-operator" cannot
            get resource "postgresclusters" in API group "postgres-operator.crunchydata.com"
            in the namespace "my-petclinic"`

    Workaround 1: Install the Service Binding Operator in the all namespaces installation mode. As a result, the appropriate cluster-scoped RBAC rule now exists and the binding succeeds.

    Workaround 2: If you cannot install the Service Binding Operator in the all namespaces installation mode, install the following role binding into the namespace where the Service Binding Operator is installed:

    Example: Role binding for Crunchy Postgres Operator

    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: service-binding-crunchy-postgres-viewer
    subjects:
      - kind: ServiceAccount
        name: service-binding-operator
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: service-binding-crunchy-postgres-viewer-role

    APPSVC-1062

  • According to the specification, when you change the ClusterWorkloadResourceMapping resources, Service Binding Operator must use the previous version of the ClusterWorkloadResourceMapping resource to remove the binding data that was being projected until now. Currently, when you change the ClusterWorkloadResourceMapping resources, the Service Binding Operator uses the latest version of the ClusterWorkloadResourceMapping resource to remove the binding data. As a result, {the servicebinding-title} might remove the binding data incorrectly. As a workaround, perform the following steps:

    1. Delete any ServiceBinding resources that use the corresponding ClusterWorkloadResourceMapping resource.
    2. Modify the ClusterWorkloadResourceMapping resource.
    3. Re-apply the ServiceBinding resources that you previously removed in step 1.

    APPSVC-1102

6.1.7. Release notes for Service Binding Operator 1.1.1

Service Binding Operator 1.1.1 is now available on OpenShift Container Platform 4.7, 4.8, 4.9, and 4.10.

6.1.7.1. Fixed issues
  • Before this update, a security vulnerability CVE-2021-38561 was noted for Service Binding Operator Helm chart. This update fixes the CVE-2021-38561 error and updates the golang.org/x/text package from v0.3.6 to v0.3.7. APPSVC-1124
  • Before this update, users of the Developer Sandbox did not have sufficient permissions to read ClusterWorkloadResourceMapping resources. As a result, Service Binding Operator prevented all service bindings from being successful. With this update, the Service Binding Operator now includes the appropriate role-based access control (RBAC) rules for any authenticated subject including the Developer Sandbox users. These RBAC rules allow the Service Binding Operator to get, list, and watch the ClusterWorkloadResourceMapping resources for the Developer Sandbox users and to process service bindings successfully. APPSVC-1135
6.1.7.2. Known issues
  • There is currently a known issue with installing Service Binding Operator in a single namespace installation mode. The absence of an appropriate namespace-scoped role-based access control (RBAC) rule prevents the successful binding of an application to a few known Operator-backed services that the Service Binding Operator can automatically detect and bind to. When this happens, it generates an error message similar to the following example:

    Example error message

    `postgresclusters.postgres-operator.crunchydata.com "hippo" is forbidden:
            User "system:serviceaccount:my-petclinic:service-binding-operator" cannot
            get resource "postgresclusters" in API group "postgres-operator.crunchydata.com"
            in the namespace "my-petclinic"`

    Workaround 1: Install the Service Binding Operator in the all namespaces installation mode. As a result, the appropriate cluster-scoped RBAC rule now exists and the binding succeeds.

    Workaround 2: If you cannot install the Service Binding Operator in the all namespaces installation mode, install the following role binding into the namespace where the Service Binding Operator is installed:

    Example: Role binding for Crunchy Postgres Operator

    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: service-binding-crunchy-postgres-viewer
    subjects:
      - kind: ServiceAccount
        name: service-binding-operator
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: service-binding-crunchy-postgres-viewer-role

    APPSVC-1062

  • Currently, when you modify the ClusterWorkloadResourceMapping resources, the Service Binding Operator does not implement correct behavior. As a workaround, perform the following steps:

    1. Delete any ServiceBinding resources that use the corresponding ClusterWorkloadResourceMapping resource.
    2. Modify the ClusterWorkloadResourceMapping resource.
    3. Re-apply the ServiceBinding resources that you previously removed in step 1.

    APPSVC-1102

6.1.8. Release notes for Service Binding Operator 1.1

Service Binding Operator is now available on OpenShift Container Platform 4.7, 4.8, 4.9, and 4.10.

6.1.8.1. New features

This section highlights what is new in Service Binding Operator 1.1:

  • Service Binding Options

    • Workload resource mapping: Define exactly where binding data needs to be projected for the secondary workloads.
    • Bind new workloads using a label selector.
6.1.8.2. Fixed issues
  • Before this update, service bindings that used label selectors to pick up workloads did not project service binding data into the new workloads that matched the given label selectors. As a result, the Service Binding Operator could not periodically bind such new workloads. With this update, service bindings now project service binding data into the new workloads that match the given label selector. The Service Binding Operator now periodically attempts to find and bind such new workloads. APPSVC-1083
6.1.8.3. Known issues
  • There is currently a known issue with installing Service Binding Operator in a single namespace installation mode. The absence of an appropriate namespace-scoped role-based access control (RBAC) rule prevents the successful binding of an application to a few known Operator-backed services that the Service Binding Operator can automatically detect and bind to. When this happens, it generates an error message similar to the following example:

    Example error message

    `postgresclusters.postgres-operator.crunchydata.com "hippo" is forbidden:
            User "system:serviceaccount:my-petclinic:service-binding-operator" cannot
            get resource "postgresclusters" in API group "postgres-operator.crunchydata.com"
            in the namespace "my-petclinic"`

    Workaround 1: Install the Service Binding Operator in the all namespaces installation mode. As a result, the appropriate cluster-scoped RBAC rule now exists and the binding succeeds.

    Workaround 2: If you cannot install the Service Binding Operator in the all namespaces installation mode, install the following role binding into the namespace where the Service Binding Operator is installed:

    Example: Role binding for Crunchy Postgres Operator

    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: service-binding-crunchy-postgres-viewer
    subjects:
      - kind: ServiceAccount
        name: service-binding-operator
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: service-binding-crunchy-postgres-viewer-role

    APPSVC-1062

  • Currently, when you modify the ClusterWorkloadResourceMapping resources, the Service Binding Operator does not implement correct behavior. As a workaround, perform the following steps:

    1. Delete any ServiceBinding resources that use the corresponding ClusterWorkloadResourceMapping resource.
    2. Modify the ClusterWorkloadResourceMapping resource.
    3. Re-apply the ServiceBinding resources that you previously removed in step 1.

    APPSVC-1102

6.1.9. Release notes for Service Binding Operator 1.0.1

Service Binding Operator is now available on OpenShift Container Platform 4.7, 4.8 and 4.9.

Service Binding Operator 1.0.1 supports OpenShift Container Platform 4.9 and later running on:

  • IBM Power Systems
  • IBM Z and LinuxONE

The custom resource definition (CRD) of the Service Binding Operator 1.0.1 supports the following APIs:

  • Service Binding with the binding.operators.coreos.com API group.
  • Service Binding (Spec API Tech Preview) with the servicebinding.io API group.

    Important

    Service Binding (Spec API Tech Preview) with the servicebinding.io API group is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

6.1.9.1. Support matrix

Some features in this release are currently in Technology Preview. These experimental features are not intended for production use.

Technology Preview Features Support Scope

In the table below, features are marked with the following statuses:

  • TP: Technology Preview
  • GA: General Availability

Note the following scope of support on the Red Hat Customer Portal for these features:

Table 6.2. Support matrix
FeatureService Binding Operator 1.0.1

binding.operators.coreos.com API group

GA

servicebinding.io API group

TP

6.1.9.2. Fixed issues
  • Before this update, binding the data values from a Cluster custom resource (CR) of the postgresql.k8s.enterpriesedb.io/v1 API collected the host binding value from the .metadata.name field of the CR. The collected binding value is an incorrect hostname and the correct hostname is available at the .status.writeService field. With this update, the annotations that the Service Binding Operator uses to expose the binding data values from the backing service CR are now modified to collect the host binding value from the .status.writeService field. The Service Binding Operator uses these modified annotations to project the correct hostname in the host and provider bindings. APPSVC-1040
  • Before this update, when you would bind a PostgresCluster CR of the postgres-operator.crunchydata.com/v1beta1 API, the binding data values did not include the values for the database certificates. As a result, the application failed to connect to the database. With this update, modifications to the annotations that the Service Binding Operator uses to expose the binding data from the backing service CR now include the database certificates. The Service Binding Operator uses these modified annotations to project the correct ca.crt, tls.crt, and tls.key certificate files. APPSVC-1045
  • Before this update, when you would bind a PerconaXtraDBCluster custom resource (CR) of the pxc.percona.com API, the binding data values did not include the port and database values. These binding values along with the others already projected are necessary for an application to successfully connect to the database service. With this update, the annotations that the Service Binding Operator uses to expose the binding data values from the backing service CR are now modified to project the additional port and database binding values. The Service Binding Operator uses these modified annotations to project the complete set of binding values that the application can use to successfully connect to the database service. APPSVC-1073
6.1.9.3. Known issues
  • Currently, when you install the Service Binding Operator in the single namespace installation mode, the absence of an appropriate namespace-scoped role-based access control (RBAC) rule prevents the successful binding of an application to a few known Operator-backed services that the Service Binding Operator can automatically detect and bind to. In addition, the following error message is generated:

    Example error message

    `postgresclusters.postgres-operator.crunchydata.com "hippo" is forbidden:
            User "system:serviceaccount:my-petclinic:service-binding-operator" cannot
            get resource "postgresclusters" in API group "postgres-operator.crunchydata.com"
            in the namespace "my-petclinic"`

    Workaround 1: Install the Service Binding Operator in the all namespaces installation mode. As a result, the appropriate cluster-scoped RBAC rule now exists and the binding succeeds.

    Workaround 2: If you cannot install the Service Binding Operator in the all namespaces installation mode, install the following role binding into the namespace where the Service Binding Operator is installed:

    Example: Role binding for Crunchy Postgres Operator

    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: service-binding-crunchy-postgres-viewer
    subjects:
      - kind: ServiceAccount
        name: service-binding-operator
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: service-binding-crunchy-postgres-viewer-role

    APPSVC-1062

6.1.10. Release notes for Service Binding Operator 1.0

Service Binding Operator is now available on OpenShift Container Platform 4.7, 4.8 and 4.9.

The custom resource definition (CRD) of the Service Binding Operator 1.0 supports the following APIs:

  • Service Binding with the binding.operators.coreos.com API group.
  • Service Binding (Spec API Tech Preview) with the servicebinding.io API group.

    Important

    Service Binding (Spec API Tech Preview) with the servicebinding.io API group is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

    For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

6.1.10.1. Support matrix

Some features in this release are currently in Technology Preview. These experimental features are not intended for production use.

Technology Preview Features Support Scope

In the table below, features are marked with the following statuses:

  • TP: Technology Preview
  • GA: General Availability

Note the following scope of support on the Red Hat Customer Portal for these features:

Table 6.3. Support matrix
FeatureService Binding Operator 1.0

binding.operators.coreos.com API group

GA

servicebinding.io API group

TP

6.1.10.2. New features

Service Binding Operator 1.0 supports OpenShift Container Platform 4.9 and later running on:

  • IBM Power Systems
  • IBM Z and LinuxONE

This section highlights what is new in Service Binding Operator 1.0:

  • Exposal of binding data from services

    • Based on annotations present in CRD, custom resources (CRs), or resources.
    • Based on descriptors present in Operator Lifecycle Manager (OLM) descriptors.
    • Support for provisioned services
  • Workload projection

    • Projection of binding data as files, with volume mounts.
    • Projection of binding data as environment variables.
  • Service Binding Options

    • Bind backing services in a namespace that is different from the workload namespace.
    • Project binding data into the specific container workloads.
    • Auto-detection of the binding data from resources owned by the backing service CR.
    • Compose custom binding data from the exposed binding data.
    • Support for non-PodSpec compliant workload resources.
  • Security

    • Support for role-based access control (RBAC).

6.1.11. Additional resources

6.2. Understanding Service Binding Operator

Application developers need access to backing services to build and connect workloads. Connecting workloads to backing services is always a challenge because each service provider suggests a different way to access their secrets and consume them in a workload. In addition, manual configuration and maintenance of this binding together of workloads and backing services make the process tedious, inefficient, and error-prone.

The Service Binding Operator enables application developers to easily bind workloads together with Operator-managed backing services, without any manual procedures to configure the binding connection.

6.2.1. Service Binding terminology

This section summarizes the basic terms used in Service Binding.

Service binding

The representation of the action of providing information about a service to a workload. Examples include establishing the exchange of credentials between a Java application and a database that it requires.

Backing service

Any service or software that the application consumes over the network as part of its normal operation. Examples include a database, a message broker, an application with REST endpoints, an event stream, an Application Performance Monitor (APM), or a Hardware Security Module (HSM).

Workload (application)

Any process running within a container. Examples include a Spring Boot application, a NodeJS Express application, or a Ruby on Rails application.

Binding data

Information about a service that you use to configure the behavior of other resources within the cluster. Examples include credentials, connection details, volume mounts, or secrets.

Binding connection

Any connection that establishes an interaction between the connected components, such as a bindable backing service and an application requiring that backing service.

6.2.2. About Service Binding Operator

The Service Binding Operator consists of a controller and an accompanying custom resource definition (CRD) for service binding. It manages the data plane for workloads and backing services. The Service Binding Controller reads the data made available by the control plane of backing services. Then, it projects this data to workloads according to the rules specified through the ServiceBinding resource.

As a result, the Service Binding Operator enables workloads to use backing services or external services by automatically collecting and sharing binding data with the workloads. The process involves making the backing service bindable and binding the workload and the service together.

6.2.2.1. Making an Operator-managed backing service bindable

To make a service bindable, as an Operator provider, you need to expose the binding data required by workloads to bind with the services provided by the Operator. You can provide the binding data either as annotations or as descriptors in the CRD of the Operator that manages the backing service.

6.2.2.2. Binding a workload together with a backing service

By using the Service Binding Operator, as an application developer, you need to declare the intent of establishing a binding connection. You must create a ServiceBinding CR that references the backing service. This action triggers the Service Binding Operator to project the exposed binding data into the workload. The Service Binding Operator receives the declared intent and binds the workload together with the backing service.

The CRD of the Service Binding Operator supports the following APIs:

  • Service Binding with the binding.operators.coreos.com API group.
  • Service Binding (Spec API) with the servicebinding.io API group.

With Service Binding Operator, you can:

  • Bind your workloads to Operator-managed backing services.
  • Automate configuration of binding data.
  • Provide service operators with a low-touch administrative experience to provision and manage access to services.
  • Enrich the development lifecycle with a consistent and declarative service binding method that eliminates discrepancies in cluster environments.

6.2.3. Key features

  • Exposal of binding data from services

    • Based on annotations present in CRD, custom resources (CRs), or resources.
  • Workload projection

    • Projection of binding data as files, with volume mounts.
    • Projection of binding data as environment variables.
  • Service Binding Options

    • Bind backing services in a namespace that is different from the workload namespace.
    • Project binding data into the specific container workloads.
    • Auto-detection of the binding data from resources owned by the backing service CR.
    • Compose custom binding data from the exposed binding data.
    • Support for non-PodSpec compliant workload resources.
  • Security

    • Support for role-based access control (RBAC).

6.2.4. API differences

The CRD of the Service Binding Operator supports the following APIs:

  • Service Binding with the binding.operators.coreos.com API group.
  • Service Binding (Spec API) with the servicebinding.io API group.

Both of these API groups have similar features, but they are not completely identical. Here is the complete list of differences between these API groups:

FeatureSupported by the binding.operators.coreos.com API groupSupported by the servicebinding.io API groupNotes

Binding to provisioned services

Yes

Yes

Not applicable (N/A)

Direct secret projection

Yes

Yes

Not applicable (N/A)

Bind as files

Yes

Yes

  • Default behavior for the service bindings of the servicebinding.io API group
  • Opt-in functionality for the service bindings of the binding.operators.coreos.com API group

Bind as environment variables

Yes

Yes

  • Default behavior for the service bindings of the binding.operators.coreos.com API group.
  • Opt-in functionality for the service bindings of the servicebinding.io API group: Environment variables are created alongside files.

Selecting workload with a label selector

Yes

Yes

Not applicable (N/A)

Detecting binding resources (.spec.detectBindingResources)

Yes

No

The servicebinding.io API group has no equivalent feature.

Naming strategies

Yes

No

There is no current mechanism within the servicebinding.io API group to interpret the templates that naming strategies use.

Container path

Yes

Partial

Because a service binding of the binding.operators.coreos.com API group can specify mapping behavior within the ServiceBinding resource, the servicebinding.io API group cannot fully support an equivalent behavior without more information about the workload.

Container name filtering

No

Yes

The binding.operators.coreos.com API group has no equivalent feature.

Secret path

Yes

No

The servicebinding.io API group has no equivalent feature.

Alternative binding sources (for example, binding data from annotations)

Yes

Allowed by Service Binding Operator

The specification requires support for getting binding data from provisioned services and secrets. However, a strict reading of the specification suggests that support for other binding data sources is allowed. Using this fact, Service Binding Operator can pull the binding data from various sources (for example, pulling binding data from annotations). Service Binding Operator supports these sources on both the API groups.

6.2.5. Additional resources

6.3. Installing Service Binding Operator

This guide walks cluster administrators through the process of installing the Service Binding Operator to an OpenShift Container Platform cluster.

You can install Service Binding Operator on OpenShift Container Platform 4.7 and later.

Prerequisites
  • You have access to an OpenShift Container Platform cluster using an account with cluster-admin permissions.
  • Your cluster has the Marketplace capability enabled or the Red Hat Operator catalog source configured manually.

6.3.1. Installing the Service Binding Operator using the web console

You can install Service Binding Operator using the OpenShift Container Platform OperatorHub. When you install the Service Binding Operator, the custom resources (CRs) required for the service binding configuration are automatically installed along with the Operator.

Procedure

  1. In the Administrator perspective of the web console, navigate to OperatorsOperatorHub.
  2. Use the Filter by keyword box to search for Service Binding Operator in the catalog. Click the Service Binding Operator tile.
  3. Read the brief description about the Operator on the Service Binding Operator page. Click Install.
  4. On the Install Operator page:

    1. Select All namespaces on the cluster (default) for the Installation Mode. This mode installs the Operator in the default openshift-operators namespace, which enables the Operator to watch and be made available to all namespaces in the cluster.
    2. Select Automatic for the Approval Strategy. This ensures that the future upgrades to the Operator are handled automatically by the Operator Lifecycle Manager (OLM). If you select the Manual approval strategy, OLM creates an update request. As a cluster administrator, you must then manually approve the OLM update request to update the Operator to the new version.
    3. Select an Update Channel.

      • By default, the stable channel enables installation of the latest stable and supported release of the Service Binding Operator.
  5. Click Install.

    Note

    The Operator is installed automatically into the openshift-operators namespace.

  6. On the Installed Operator — ready for use pane, click View Operator. You will see the Operator listed on the Installed Operators page.
  7. Verify that the Status is set to Succeeded to confirm successful installation of Service Binding Operator.

6.3.2. Additional resources

6.4. Getting started with service binding

The Service Binding Operator manages the data plane for workloads and backing services. This guide provides instructions with examples to help you create a database instance, deploy an application, and use the Service Binding Operator to create a binding connection between the application and the database service.

Prerequisites
  • You have access to an OpenShift Container Platform cluster using an account with cluster-admin permissions.
  • You have installed the oc CLI.
  • You have installed Service Binding Operator from OperatorHub.
  • You have installed the 5.1.2 version of the Crunchy Postgres for Kubernetes Operator from OperatorHub using the v5 Update channel. The installed Operator is available in an appropriate namespace, such as the my-petclinic namespace.

    Note

    You can create the namespace using the oc create namespace my-petclinic command.

6.4.1. Creating a PostgreSQL database instance

To create a PostgreSQL database instance, you must create a PostgresCluster custom resource (CR) and configure the database.

Procedure

  1. Create the PostgresCluster CR in the my-petclinic namespace by running the following command in shell:

    $ oc apply -n my-petclinic -f - << EOD
    ---
    apiVersion: postgres-operator.crunchydata.com/v1beta1
    kind: PostgresCluster
    metadata:
      name: hippo
    spec:
      image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-14.4-0
      postgresVersion: 14
      instances:
        - name: instance1
          dataVolumeClaimSpec:
            accessModes:
            - "ReadWriteOnce"
            resources:
              requests:
                storage: 1Gi
      backups:
        pgbackrest:
          image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:ubi8-2.38-0
          repos:
          - name: repo1
            volume:
              volumeClaimSpec:
                accessModes:
                - "ReadWriteOnce"
                resources:
                  requests:
                    storage: 1Gi
    EOD

    The annotations added in this PostgresCluster CR enable the service binding connection and trigger the Operator reconciliation.

    The output verifies that the database instance is created:

    Example output

    postgrescluster.postgres-operator.crunchydata.com/hippo created

  2. After you have created the database instance, ensure that all the pods in the my-petclinic namespace are running:

    $ oc get pods -n my-petclinic

    The output, which takes a few minutes to display, verifies that the database is created and configured:

    Example output

    NAME                                     READY    STATUS      RESTARTS   AGE
    hippo-backup-9rxm-88rzq                   0/1     Completed   0          2m2s
    hippo-instance1-6psd-0                    4/4     Running     0          3m28s
    hippo-repo-host-0                         2/2     Running     0          3m28s

    After the database is configured, you can deploy the sample application and connect it to the database service.

6.4.2. Deploying the Spring PetClinic sample application

To deploy the Spring PetClinic sample application on an OpenShift Container Platform cluster, you must use a deployment configuration and configure your local environment to be able to test the application.

Procedure

  1. Deploy the spring-petclinic application with the PostgresCluster custom resource (CR) by running the following command in shell:

    $ oc apply -n my-petclinic -f - << EOD
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: spring-petclinic
      labels:
        app: spring-petclinic
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: spring-petclinic
      template:
        metadata:
          labels:
            app: spring-petclinic
        spec:
          containers:
            - name: app
              image: quay.io/service-binding/spring-petclinic:latest
              imagePullPolicy: Always
              env:
              - name: SPRING_PROFILES_ACTIVE
                value: postgres
              ports:
              - name: http
                containerPort: 8080
    ---
    apiVersion: v1
    kind: Service
    metadata:
      labels:
        app: spring-petclinic
      name: spring-petclinic
    spec:
      type: NodePort
      ports:
        - port: 80
          protocol: TCP
          targetPort: 8080
      selector:
        app: spring-petclinic
    EOD

    The output verifies that the Spring PetClinic sample application is created and deployed:

    Example output

    deployment.apps/spring-petclinic created
    service/spring-petclinic created

    Note

    If you are deploying the application using Container images in the Developer perspective of the web console, you must enter the following environment variables under the Deployment section of the Advanced options:

    • Name: SPRING_PROFILES_ACTIVE
    • Value: postgres
  2. Verify that the application is not yet connected to the database service by running the following command:

    $ oc get pods -n my-petclinic

    The output takes a few minutes to display the CrashLoopBackOff status:

    Example output

    NAME                                READY   STATUS             RESTARTS      AGE
    spring-petclinic-5b4c7999d4-wzdtz   0/1     CrashLoopBackOff   4 (13s ago)   2m25s

    At this stage, the pod fails to start. If you try to interact with the application, it returns errors.

  3. Expose the service to create a route for your application:

    $ oc expose service spring-petclinic -n my-petclinic

    The output verifies that the spring-petclinic service is exposed and a route for the Spring PetClinic sample application is created:

    Example output

    route.route.openshift.io/spring-petclinic exposed

You can now use the Service Binding Operator to connect the application to the database service.

6.4.3. Connecting the Spring PetClinic sample application to the PostgreSQL database service

To connect the sample application to the database service, you must create a ServiceBinding custom resource (CR) that triggers the Service Binding Operator to project the binding data into the application.

Procedure

  1. Create a ServiceBinding CR to project the binding data:

    $ oc apply -n my-petclinic -f - << EOD
    ---
    apiVersion: binding.operators.coreos.com/v1alpha1
    kind: ServiceBinding
    metadata:
      name: spring-petclinic-pgcluster
    spec:
      services: 1
        - group: postgres-operator.crunchydata.com
          version: v1beta1
          kind: PostgresCluster 2
          name: hippo
      application: 3
        name: spring-petclinic
        group: apps
        version: v1
        resource: deployments
    EOD
    1
    Specifies a list of service resources.
    2
    The CR of the database.
    3
    The sample application that points to a Deployment or any other similar resource with an embedded PodSpec.

    The output verifies that the ServiceBinding CR is created to project the binding data into the sample application.

    Example output

    servicebinding.binding.operators.coreos.com/spring-petclinic created

  2. Verify that the request for service binding is successful:

    $ oc get servicebindings -n my-petclinic

    Example output

    NAME                         READY   REASON              AGE
    spring-petclinic-pgcluster   True    ApplicationsBound   7s

    By default, the values from the binding data of the database service are projected as files into the workload container that runs the sample application. For example, all the values from the Secret resource are projected into the bindings/spring-petclinic-pgcluster directory.

    Note

    Optionally, you can also verify that the files in the application contain the projected binding data, by printing out the directory contents:

    $ for i in username password host port type; do oc exec -it deploy/spring-petclinic -n my-petclinic -- /bin/bash -c 'cd /tmp; find /bindings/*/'$i' -exec echo -n {}:" " \; -exec cat {} \;'; echo; done

    Example output: With all the values from the secret resource

    /bindings/spring-petclinic-pgcluster/username: <username>
    /bindings/spring-petclinic-pgcluster/password: <password>
    /bindings/spring-petclinic-pgcluster/host: hippo-primary.my-petclinic.svc
    /bindings/spring-petclinic-pgcluster/port: 5432
    /bindings/spring-petclinic-pgcluster/type: postgresql

  3. Set up the port forwarding from the application port to access the sample application from your local environment:

    $ oc port-forward --address 0.0.0.0 svc/spring-petclinic 8080:80 -n my-petclinic

    Example output

    Forwarding from 0.0.0.0:8080 -> 8080
    Handling connection for 8080

  4. Access http://localhost:8080/petclinic.

    You can now remotely access the Spring PetClinic sample application at localhost:8080 and see that the application is now connected to the database service.

6.4.4. Additional resources

6.5. Getting started with service binding on IBM Power, IBM Z, and IBM(R) LinuxONE

The Service Binding Operator manages the data plane for workloads and backing services. This guide provides instructions with examples to help you create a database instance, deploy an application, and use the Service Binding Operator to create a binding connection between the application and the database service.

Prerequisites
  • You have access to an OpenShift Container Platform cluster using an account with cluster-admin permissions.
  • You have installed the oc CLI.
  • You have installed the Service Binding Operator from OperatorHub.

6.5.1. Deploying a PostgreSQL Operator

Procedure

  1. To deploy the Dev4Devs PostgreSQL Operator in the my-petclinic namespace run the following command in shell:
$ oc apply -f - << EOD
---
apiVersion: v1
kind: Namespace
metadata:
  name: my-petclinic
---
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: postgres-operator-group
  namespace: my-petclinic
---
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: ibm-multiarch-catalog
  namespace: openshift-marketplace
spec:
  sourceType: grpc
  image: quay.io/ibm/operator-registry-<architecture> 1
  imagePullPolicy: IfNotPresent
  displayName: ibm-multiarch-catalog
  updateStrategy:
    registryPoll:
      interval: 30m
---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: postgresql-operator-dev4devs-com
  namespace: openshift-operators
spec:
  channel: alpha
  installPlanApproval: Automatic
  name: postgresql-operator-dev4devs-com
  source: ibm-multiarch-catalog
  sourceNamespace: openshift-marketplace
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: database-view
  labels:
    servicebinding.io/controller: "true"
rules:
  - apiGroups:
      - postgresql.dev4devs.com
    resources:
      - databases
    verbs:
      - get
      - list
EOD
1
The Operator image.
  • For IBM Power: quay.io/ibm/operator-registry-ppc64le:release-4.9
  • For IBM Z and IBM® LinuxONE: quay.io/ibm/operator-registry-s390x:release-4.8

Verification

  1. After the operator is installed, list the operator subscriptions in the openshift-operators namespace:

    $ oc get subs -n openshift-operators

    Example output

    NAME                               PACKAGE                            SOURCE                  CHANNEL
    postgresql-operator-dev4devs-com   postgresql-operator-dev4devs-com   ibm-multiarch-catalog   alpha
    rh-service-binding-operator        rh-service-binding-operator        redhat-operators        stable

6.5.2. Creating a PostgreSQL database instance

To create a PostgreSQL database instance, you must create a Database custom resource (CR) and configure the database.

Procedure

  1. Create the Database CR in the my-petclinic namespace by running the following command in shell:

    $ oc apply -f - << EOD
    apiVersion: postgresql.dev4devs.com/v1alpha1
    kind: Database
    metadata:
      name: sampledatabase
      namespace: my-petclinic
      annotations:
        host: sampledatabase
        type: postgresql
        port: "5432"
        service.binding/database: 'path={.spec.databaseName}'
        service.binding/port: 'path={.metadata.annotations.port}'
        service.binding/password: 'path={.spec.databasePassword}'
        service.binding/username: 'path={.spec.databaseUser}'
        service.binding/type: 'path={.metadata.annotations.type}'
        service.binding/host: 'path={.metadata.annotations.host}'
    spec:
      databaseCpu: 30m
      databaseCpuLimit: 60m
      databaseMemoryLimit: 512Mi
      databaseMemoryRequest: 128Mi
      databaseName: "sampledb"
      databaseNameKeyEnvVar: POSTGRESQL_DATABASE
      databasePassword: "samplepwd"
      databasePasswordKeyEnvVar: POSTGRESQL_PASSWORD
      databaseStorageRequest: 1Gi
      databaseUser: "sampleuser"
      databaseUserKeyEnvVar: POSTGRESQL_USER
      image: registry.redhat.io/rhel8/postgresql-13:latest
      databaseStorageClassName: nfs-storage-provisioner
      size: 1
    EOD

    The annotations added in this Database CR enable the service binding connection and trigger the Operator reconciliation.

    The output verifies that the database instance is created:

    Example output

    database.postgresql.dev4devs.com/sampledatabase created

  2. After you have created the database instance, ensure that all the pods in the my-petclinic namespace are running:

    $ oc get pods -n my-petclinic

    The output, which takes a few minutes to display, verifies that the database is created and configured:

    Example output

    NAME                                     READY    STATUS      RESTARTS   AGE
    sampledatabase-cbc655488-74kss            0/1     Running        0       32s

After the database is configured, you can deploy the sample application and connect it to the database service.

6.5.3. Deploying the Spring PetClinic sample application

To deploy the Spring PetClinic sample application on an OpenShift Container Platform cluster, you must use a deployment configuration and configure your local environment to be able to test the application.

Procedure

  1. Deploy the spring-petclinic application with the PostgresCluster custom resource (CR) by running the following command in shell:

    $ oc apply -n my-petclinic -f - << EOD
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: spring-petclinic
      labels:
        app: spring-petclinic
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: spring-petclinic
      template:
        metadata:
          labels:
            app: spring-petclinic
        spec:
          containers:
            - name: app
              image: quay.io/service-binding/spring-petclinic:latest
              imagePullPolicy: Always
              env:
              - name: SPRING_PROFILES_ACTIVE
                value: postgres
              - name: org.springframework.cloud.bindings.boot.enable
                value: "true"
              ports:
              - name: http
                containerPort: 8080
    ---
    apiVersion: v1
    kind: Service
    metadata:
      labels:
        app: spring-petclinic
      name: spring-petclinic
    spec:
      type: NodePort
      ports:
        - port: 80
          protocol: TCP
          targetPort: 8080
      selector:
        app: spring-petclinic
    EOD

    The output verifies that the Spring PetClinic sample application is created and deployed:

    Example output

    deployment.apps/spring-petclinic created
    service/spring-petclinic created

    Note

    If you are deploying the application using Container images in the Developer perspective of the web console, you must enter the following environment variables under the Deployment section of the Advanced options:

    • Name: SPRING_PROFILES_ACTIVE
    • Value: postgres
  2. Verify that the application is not yet connected to the database service by running the following command:

    $ oc get pods -n my-petclinic

    It takes take a few minutes until the CrashLoopBackOff status is displayed:

    Example output

    NAME                                READY   STATUS             RESTARTS      AGE
    spring-petclinic-5b4c7999d4-wzdtz   0/1     CrashLoopBackOff   4 (13s ago)   2m25s

    At this stage, the pod fails to start. If you try to interact with the application, it returns errors.

You can now use the Service Binding Operator to connect the application to the database service.

6.5.4. Connecting the Spring PetClinic sample application to the PostgreSQL database service

To connect the sample application to the database service, you must create a ServiceBinding custom resource (CR) that triggers the Service Binding Operator to project the binding data into the application.

Procedure

  1. Create a ServiceBinding CR to project the binding data:

    $ oc apply -n my-petclinic -f - << EOD
    ---
    apiVersion: binding.operators.coreos.com/v1alpha1
    kind: ServiceBinding
    metadata:
        name: spring-petclinic-pgcluster
    spec:
      services: 1
        - group: postgresql.dev4devs.com
          kind: Database 2
          name: sampledatabase
          version: v1alpha1
      application: 3
        name: spring-petclinic
        group: apps
        version: v1
        resource: deployments
    EOD
    1
    Specifies a list of service resources.
    2
    The CR of the database.
    3
    The sample application that points to a Deployment or any other similar resource with an embedded PodSpec.

    The output verifies that the ServiceBinding CR is created to project the binding data into the sample application.

    Example output

    servicebinding.binding.operators.coreos.com/spring-petclinic created

  2. Verify that the request for service binding is successful:

    $ oc get servicebindings -n my-petclinic

    Example output

    NAME                          READY   REASON              AGE
    spring-petclinic-postgresql   True    ApplicationsBound   47m

    By default, the values from the binding data of the database service are projected as files into the workload container that runs the sample application. For example, all the values from the Secret resource are projected into the bindings/spring-petclinic-pgcluster directory.

  3. Once this is created, you can go to the topology to see the visual connection.

    Figure 6.1. Connecting spring-petclinic to a sample database

    img power
  4. Set up the port forwarding from the application port to access the sample application from your local environment:

    $ oc port-forward --address 0.0.0.0 svc/spring-petclinic 8080:80 -n my-petclinic

    Example output

    Forwarding from 0.0.0.0:8080 -> 8080
    Handling connection for 8080

  5. Access http://localhost:8080.

    You can now remotely access the Spring PetClinic sample application at localhost:8080 and see that the application is now connected to the database service.

6.5.5. Additional resources

6.6. Exposing binding data from a service

Application developers need access to backing services to build and connect workloads. Connecting workloads to backing services is always a challenge because each service provider requires a different way to access their secrets and consume them in a workload.

The Service Binding Operator enables application developers to easily bind workloads together with operator-managed backing services, without any manual procedures to configure the binding connection. For the Service Binding Operator to provide the binding data, as an Operator provider or user who creates backing services, you must expose the binding data to be automatically detected by the Service Binding Operator. Then, the Service Binding Operator automatically collects the binding data from the backing service and shares it with a workload to provide a consistent and predictable experience.

6.6.1. Methods of exposing binding data

This section describes the methods you can use to expose the binding data.

Ensure that you know and understand your workload requirements and environment, and how it works with the provided services.

Binding data is exposed under the following circumstances:

  • Backing service is available as a provisioned service resource.

    The service you intend to connect to is compliant with the Service Binding specification. You must create a Secret resource with all the required binding data values and reference it in the backing service custom resource (CR). The detection of all the binding data values is automatic.

  • Backing service is not available as a provisioned service resource.

    You must expose the binding data from the backing service. Depending on your workload requirements and environment, you can choose any of the following methods to expose the binding data:

    • Direct secret reference
    • Declaring binding data through custom resource definition (CRD) or CR annotations
    • Detection of binding data through owned resources
6.6.1.1. Provisioned service

Provisioned service represents a backing service CR with a reference to a Secret resource placed in the .status.binding.name field of the backing service CR.

As an Operator provider or the user who creates backing services, you can use this method to be compliant with the Service Binding specification, by creating a Secret resource and referencing it in the .status.binding.name section of the backing service CR. This Secret resource must provide all the binding data values required for a workload to connect to the backing service.

The following examples show an AccountService CR that represents a backing service and a Secret resource referenced from the CR.

Example: AccountService CR

apiVersion: example.com/v1alpha1
kind: AccountService
name: prod-account-service
spec:
# ...
status:
  binding:
    name: hippo-pguser-hippo

Example: Referenced Secret resource

apiVersion: v1
kind: Secret
metadata:
  name: hippo-pguser-hippo
data:
  password: "<password>"
  user: "<username>"
# ...

When creating a service binding resource, you can directly give the details of the AccountService resource in the ServiceBinding specification as follows:

Example: ServiceBinding resource

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
  name: account-service
spec:
# ...
  services:
  - group: "example.com"
    version: v1alpha1
    kind: AccountService
    name: prod-account-service
  application:
    name: spring-petclinic
    group: apps
    version: v1
    resource: deployments

Example: ServiceBinding resource in Specification API

apiVersion: servicebinding.io/v1beta1
kind: ServiceBinding
metadata:
  name: account-service
spec:
# ...
  service:
    apiVersion: example.com/v1alpha1
    kind: AccountService
    name: prod-account-service
  workload:
    apiVersion: apps/v1
    kind: Deployment
    name: spring-petclinic

This method exposes all the keys in the hippo-pguser-hippo referenced Secret resource as binding data that is to be projected into the workload.

6.6.1.2. Direct secret reference

You can use this method, if all the required binding data values are available in a Secret resource that you can reference in your Service Binding definition. In this method, a ServiceBinding resource directly references a Secret resource to connect to a service. All the keys in the Secret resource are exposed as binding data.

Example: Specification with the binding.operators.coreos.com API

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
  name: account-service
spec:
# ...
  services:
  - group: ""
    version: v1
    kind: Secret
    name: hippo-pguser-hippo

Example: Specification that is compliant with the servicebinding.io API

apiVersion: servicebinding.io/v1beta1
kind: ServiceBinding
metadata:
  name: account-service
spec:
# ...
  service:
    apiVersion: v1
    kind: Secret
    name: hippo-pguser-hippo

6.6.1.3. Declaring binding data through CRD or CR annotations

You can use this method to annotate the resources of the backing service to expose the binding data with specific annotations. Adding annotations under the metadata section alters the CRs and CRDs of the backing services. Service Binding Operator detects the annotations added to the CRs and CRDs and then creates a Secret resource with the values extracted based on the annotations.

The following examples show the annotations that are added under the metadata section and a referenced ConfigMap object from a resource:

Example: Exposing binding data from a Secret object defined in the CR annotations

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'
# ...

The previous example places the name of the secret name in the {.metadata.name}-pguser-{.metadata.name} template that resolves to hippo-pguser-hippo. The template can contain multiple JSONPath expressions.

Example: Referenced Secret object from a resource

apiVersion: v1
kind: Secret
metadata:
  name: hippo-pguser-hippo
data:
  password: "<password>"
  user: "<username>"

Example: Exposing binding data from a ConfigMap object defined in the CR annotations

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    service.binding: 'path={.metadata.name}-config,objectType=ConfigMap'
# ...

The previous example places the name of the config map in the {.metadata.name}-config template that resolves to hippo-config. The template can contain multiple JSONPath expressions.

Example: Referenced ConfigMap object from a resource

apiVersion: v1
kind: ConfigMap
metadata:
  name: hippo-config
data:
  db_timeout: "10s"
  user: "hippo"

6.6.1.4. Detection of binding data through owned resources

You can use this method if your backing service owns one or more Kubernetes resources such as route, service, config map, or secret that you can use to detect the binding data. In this method, the Service Binding Operator detects the binding data from resources owned by the backing service CR.

The following examples show the detectBindingResources API option set to true in the ServiceBinding CR:

Example

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
  name: spring-petclinic-detect-all
  namespace: my-petclinic
spec:
  detectBindingResources: true
  services:
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo
  application:
    name: spring-petclinic
    group: apps
    version: v1
    resource: deployments

In the previous example, PostgresCluster custom service resource owns one or more Kubernetes resources such as route, service, config map, or secret.

The Service Binding Operator automatically detects the binding data exposed on each of the owned resources.

6.6.2. Data model

The data model used in the annotations follows specific conventions.

Service binding annotations must use the following convention:

service.binding(/<NAME>)?:
    "<VALUE>|(path=<JSONPATH_TEMPLATE>(,objectType=<OBJECT_TYPE>)?(,elementType=<ELEMENT_TYPE>)?(,sourceKey=<SOURCE_KEY>)?(,sourceValue=<SOURCE_VALUE>)?)"

where:

<NAME>

Specifies the name under which the binding value is to be exposed. You can exclude it only when the objectType parameter is set to Secret or ConfigMap.

<VALUE>

Specifies the constant value exposed when no path is set.

The data model provides the details on the allowed values and semantic for the path, elementType, objectType, sourceKey, and sourceValue parameters.

Table 6.4. Parameters and their descriptions
ParameterDescriptionDefault value

path

JSONPath template that consists JSONPath expressions enclosed by curly braces {}.

N/A

elementType

Specifies whether the value of the element referenced in the path parameter complies with any one of the following types:

  • string
  • sliceOfStrings
  • sliceOfMaps

string

objectType

Specifies whether the value of the element indicated in the path parameter refers to a ConfigMap, Secret, or plain string in the current namespace.

Secret, if elementType is non-string.

sourceKey

Specifies the key in the ConfigMap or Secret resource to be added to the binding secret when collecting the binding data.

Note:

  • When used in conjunction with elementType=sliceOfMaps, the sourceKey parameter specifies the key in the slice of maps whose value is used as a key in the binding secret.
  • Use this optional parameter to expose a specific entry in the referenced Secret or ConfigMap resource as binding data.
  • When not specified, all keys and values from the Secret or ConfigMap resource are exposed and are added to the binding secret.

N/A

sourceValue

Specifies the key in the slice of maps.

Note:

  • The value of this key is used as the base to generate the value of the entry for the key-value pair to be added to the binding secret.
  • In addition, the value of the sourceKey is used as the key of the entry for the key-value pair to be added to the binding secret.
  • It is mandatory only if elementType=sliceOfMaps.

N/A

Note

The sourceKey and sourceValue parameters are applicable only if the element indicated in the path parameter refers to a ConfigMap or Secret resource.

6.6.3. Setting annotations mapping to be optional

You can have optional fields in the annotations. For example, a path to the credentials might not be present if the service endpoint does not require authentication. In such cases, a field might not exist in the target path of the annotations. As a result, Service Binding Operator generates an error, by default.

As a service provider, to indicate whether you require annotations mapping, you can set a value for the optional flag in your annotations when enabling services. Service Binding Operator provides annotations mapping only if the target path is available. When the target path is not available, the Service Binding Operator skips the optional mapping and continues with the projection of the existing mappings without throwing any errors.

Procedure

  • To make a field in the annotations optional, set the optional flag value to true:

    Example

    apiVersion: apps.example.org/v1beta1
    kind: Database
    metadata:
      name: my-db
      namespace: my-petclinic
      annotations:
        service.binding/username: path={.spec.name},optional=true
    # ...

Note
  • If you set the optional flag value to false and the Service Binding Operator is unable to find the target path, the Operator fails the annotations mapping.
  • If the optional flag has no value set, the Service Binding Operator considers the value as false by default and fails the annotations mapping.

6.6.4. RBAC requirements

To expose the backing service binding data using the Service Binding Operator, you require certain Role-based access control (RBAC) permissions. Specify certain verbs under the rules field of the ClusterRole resource to grant the RBAC permissions for the backing service resources. When you define these rules, you allow the Service Binding Operator to read the binding data of the backing service resources throughout the cluster. If the users do not have permissions to read binding data or modify application resource, the Service Binding Operator prevents such users to bind services to application. Adhering to the RBAC requirements avoids unnecessary permission elevation for the user and prevents access to unauthorized services or applications.

The Service Binding Operator performs requests against the Kubernetes API using a dedicated service account. By default, this account has permissions to bind services to workloads, both represented by the following standard Kubernetes or OpenShift objects:

  • Deployments
  • DaemonSets
  • ReplicaSets
  • StatefulSets
  • DeploymentConfigs

The Operator service account is bound to an aggregated cluster role, allowing Operator providers or cluster administrators to enable binding custom service resources to workloads. To grant the required permissions within a ClusterRole, label it with the servicebinding.io/controller flag and set the flag value to true. The following example shows how to allow the Service Binding Operator to get, watch, and list the custom resources (CRs) of Crunchy PostgreSQL Operator:

Example: Enable binding to PostgreSQL database instances provisioned by Crunchy PostgreSQL Operator

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: postgrescluster-reader
  labels:
     servicebinding.io/controller: "true"
rules:
- apiGroups:
    - postgres-operator.crunchydata.com
  resources:
    - postgresclusters
  verbs:
    - get
    - watch
    - list
  ...

This cluster role can be deployed during the installation of the backing service Operator.

6.6.5. Categories of exposable binding data

The Service Binding Operator enables you to expose the binding data values from the backing service resources and custom resource definitions (CRDs).

This section provides examples to show how you can use the various categories of exposable binding data. You must modify these examples to suit your work environment and requirements.

6.6.5.1. Exposing a string from a resource

The following example shows how to expose the string from the metadata.name field of the PostgresCluster custom resource (CR) as a username:

Example

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    service.binding/username: path={.metadata.name}
# ...

6.6.5.2. Exposing a constant value as the binding item

The following examples show how to expose a constant value from the PostgresCluster custom resource (CR):

Example: Exposing a constant value

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    "service.binding/type": "postgresql" 1

1
Binding type to be exposed with the postgresql value.
6.6.5.3. Exposing an entire config map or secret that is referenced from a resource

The following examples show how to expose an entire secret through annotations:

Example: Exposing an entire secret through annotations

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'

Example: The referenced secret from the backing service resource

apiVersion: v1
kind: Secret
metadata:
  name: hippo-pguser-hippo
data:
  password: "<password>"
  user: "<username>"

6.6.5.4. Exposing a specific entry from a config map or secret that is referenced from a resource

The following examples show how to expose a specific entry from a config map through annotations:

Example: Exposing an entry from a config map through annotations

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    service.binding: 'path={.metadata.name}-config,objectType=ConfigMap,sourceKey=user'

Example: The referenced config map from the backing service resource

The binding data should have a key with name as db_timeout and value as 10s:

apiVersion: v1
kind: ConfigMap
metadata:
  name: hippo-config
data:
  db_timeout: "10s"
  user: "hippo"
6.6.5.5. Exposing a resource definition value

The following example shows how to expose a resource definition value through annotations:

Example: Exposing a resource definition value through annotations

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    service.binding/username: path={.metadata.name}
    ...

6.6.5.6. Exposing entries of a collection with the key and value from each entry

The following example shows how to expose the entries of a collection with the key and value from each entry through annotations:

Example: Exposing the entries of a collection through annotations

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    "service.binding/uri": "path={.status.connections},elementType=sliceOfMaps,sourceKey=type,sourceValue=url"
spec:
# ...
status:
  connections:
    - type: primary
      url: primary.example.com
    - type: secondary
      url: secondary.example.com
    - type: '404'
      url: black-hole.example.com

The following example shows how the previous entries of a collection in annotations are projected into the bound application.

Example: Binding data files

/bindings/<binding-name>/uri_primary => primary.example.com
/bindings/<binding-name>/uri_secondary => secondary.example.com
/bindings/<binding-name>/uri_404 => black-hole.example.com

Example: Configuration from a backing service resource

status:
  connections:
    - type: primary
      url: primary.example.com
    - type: secondary
      url: secondary.example.com
    - type: '404'
      url: black-hole.example.com

The previous example helps you to project all those values with keys such as primary, secondary, and so on.

6.6.5.7. Exposing items of a collection with one key per item

The following example shows how to expose the items of a collection with one key per item through annotations:

Example: Exposing the items of a collection through annotations

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    "service.binding/tags": "path={.spec.tags},elementType=sliceOfStrings"
spec:
    tags:
      - knowledge
      - is
      - power

The following example shows how the previous items of a collection in annotations are projected into the bound application.

Example: Binding data files

/bindings/<binding-name>/tags_0 => knowledge
/bindings/<binding-name>/tags_1 => is
/bindings/<binding-name>/tags_2 => power

Example: Configuration from a backing service resource

spec:
  tags:
  - knowledge
  - is
  - power

6.6.5.8. Exposing values of collection entries with one key per entry value

The following example shows how to expose the values of collection entries with one key per entry value through annotations:

Example: Exposing the values of collection entries through annotations

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: my-petclinic
  annotations:
    "service.binding/url": "path={.spec.connections},elementType=sliceOfStrings,sourceValue=url"
spec:
  connections:
    - type: primary
      url: primary.example.com
    - type: secondary
      url: secondary.example.com
    - type: '404'
      url: black-hole.example.com

The following example shows how the previous values of a collection in annotations are projected into the bound application.

Example: Binding data files

/bindings/<binding-name>/url_0 => primary.example.com
/bindings/<binding-name>/url_1 => secondary.example.com
/bindings/<binding-name>/url_2 => black-hole.example.com

6.6.6. Additional resources

6.7. Projecting binding data

This section provides information on how you can consume the binding data.

6.7.1. Consumption of binding data

After the backing service exposes the binding data, for a workload to access and consume this data, you must project it into the workload from a backing service. Service Binding Operator automatically projects this set of data into the workload in the following methods:

  1. By default, as files.
  2. As environment variables, after you configure the .spec.bindAsFiles parameter from the ServiceBinding resource.

6.7.2. Configuration of the directory path to project the binding data inside workload container

By default, Service Binding Operator mounts the binding data as files at a specific directory in your workload resource. You can configure the directory path using the SERVICE_BINDING_ROOT environment variable setup in the container where your workload runs.

Example: Binding data mounted as files

$SERVICE_BINDING_ROOT 1
├── account-database 2
│   ├── type 3
│   ├── provider 4
│   ├── uri
│   ├── username
│   └── password
└── transaction-event-stream 5
    ├── type
    ├── connection-count
    ├── uri
    ├── certificates
    └── private-key

1
Root directory.
2 5
Directory that stores the binding data.
3
Mandatory identifier that identifies the type of the binding data projected into the corresponding directory.
4
Optional: Identifier to identify the provider so that the application can identify the type of backing service it can connect to.

To consume the binding data as environment variables, use the built-in language feature of your programming language of choice that can read environment variables.

Example: Python client usage

import os
username = os.getenv("USERNAME")
password = os.getenv("PASSWORD")

Warning

For using the binding data directory name to look up the binding data

Service Binding Operator uses the ServiceBinding resource name (.metadata.name) as the binding data directory name. The spec also provides a way to override that name through the .spec.name field. As a result, there is a chance for binding data name collision if there are multiple ServiceBinding resources in the namespace. However, due to the nature of the volume mount in Kubernetes, the binding data directory will contain values from only one of the Secret resources.

6.7.2.1. Computation of the final path for projecting the binding data as files

The following table summarizes the configuration of how the final path for the binding data projection is computed when files are mounted at a specific directory:

Table 6.5. Summary of the final path computation
SERVICE_BINDING_ROOTFinal path

Not available

/bindings/<ServiceBinding_ResourceName>

dir/path/root

dir/path/root/<ServiceBinding_ResourceName>

In the previous table, the <ServiceBinding_ResourceName> entry specifies the name of the ServiceBinding resource that you configure in the .metadata.name section of the custom resource (CR).

Note

By default, the projected files get their permissions set to 0644. Service Binding Operator cannot set specific permissions due to a bug in Kubernetes that causes issues if the service expects specific permissions such as 0600. As a workaround, you can modify the code of the program or the application that is running inside a workload resource to copy the file to the /tmp directory and set the appropriate permissions.

To access and consume the binding data within the existing SERVICE_BINDING_ROOT environment variable, use the built-in language feature of your programming language of choice that can read environment variables.

Example: Python client usage

from pyservicebinding import binding
try:
    sb = binding.ServiceBinding()
except binding.ServiceBindingRootMissingError as msg:
    # log the error message and retry/exit
    print("SERVICE_BINDING_ROOT env var not set")
sb = binding.ServiceBinding()
bindings_list = sb.bindings("postgresql")

In the previous example, the bindings_list variable contains the binding data for the postgresql database service type.

6.7.3. Projecting the binding data

Depending on your workload requirements and environment, you can choose to project the binding data either as files or environment variables.

Prerequisites

  • You understand the following concepts:

    • Environment and requirements of your workload, and how it works with the provided services.
    • Consumption of the binding data in your workload resource.
    • Configuration of how the final path for data projection is computed for the default method.
  • The binding data is exposed from the backing service.

Procedure

  1. To project the binding data as files, determine the destination folder by ensuring that the existing SERVICE_BINDING_ROOT environment variable is present in the container where your workload runs.
  2. To project the binding data as environment variables, set the value for the .spec.bindAsFiles parameter to false from the ServiceBinding resource in the custom resource (CR).

6.7.4. Additional resources

6.8. Binding workloads using Service Binding Operator

Application developers must bind a workload to one or more backing services by using a binding secret. This secret is generated for the purpose of storing information to be consumed by the workload.

As an example, consider that the service you want to connect to is already exposing the binding data. In this case, you would also need a workload to be used along with the ServiceBinding custom resource (CR). By using this ServiceBinding CR, the workload sends a binding request with the details of the services to bind with.

Example of ServiceBinding CR

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
    name: spring-petclinic-pgcluster
    namespace: my-petclinic
spec:
    services: 1
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo
    application: 2
      name: spring-petclinic
      group: apps
      version: v1
      resource: deployments

1
Specifies a list of service resources.
2
The sample application that points to a Deployment or any other similar resource with an embedded PodSpec.

As shown in the previous example, you can also directly use a ConfigMap or a Secret itself as a service resource to be used as a source of binding data.

6.8.1. Naming strategies

Naming strategies are available only for the binding.operators.coreos.com API group.

Naming strategies use Go templates to help you define custom binding names through the service binding request. Naming strategies apply for all attributes including the mappings in the ServiceBinding custom resource (CR).

A backing service projects the binding names as files or environment variables into the workload. If a workload expects the projected binding names in a particular format, but the binding names to be projected from the backing service are not available in that format, then you can change the binding names using naming strategies.

Predefined post-processing functions

While using naming strategies, depending on the expectations or requirements of your workload, you can use the following predefined post-processing functions in any combination to convert the character strings:

  • upper: Converts the character strings into capital or uppercase letters.
  • lower: Converts the character strings into lowercase letters.
  • title: Converts the character strings where the first letter of each word is capitalized except for certain minor words.

Predefined naming strategies

Binding names declared through annotations are processed for their name change before their projection into the workload according to the following predefined naming strategies:

  • none: When applied, there are no changes in the binding names.

    Example

    After the template compilation, the binding names take the {{ .name }} form.

    host: hippo-pgbouncer
    port: 5432
  • upper: Applied when no namingStrategy is defined. When applied, converts all the character strings of the binding name key into capital or uppercase letters.

    Example

    After the template compilation, the binding names take the {{ .service.kind | upper}}_{{ .name | upper }} form.

    DATABASE_HOST: hippo-pgbouncer
    DATABASE_PORT: 5432

    If your workload requires a different format, you can define a custom naming strategy and change the binding name using a prefix and a separator, for example, PORT_DATABASE.

Note
  • When the binding names are projected as files, by default the predefined none naming strategy is applied, and the binding names do not change.
  • When the binding names are projected as environment variables and no namingStrategy is defined, by default the predefined uppercase naming strategy is applied.
  • You can override the predefined naming strategies by defining custom naming strategies using different combinations of custom binding names and predefined post-processing functions.

6.8.2. Advanced binding options

You can define the ServiceBinding custom resource (CR) to use the following advanced binding options:

  • Changing binding names: This option is available only for the binding.operators.coreos.com API group.
  • Composing custom binding data: This option is available only for the binding.operators.coreos.com API group.
  • Binding workloads using label selectors: This option is available for both the binding.operators.coreos.com and servicebinding.io API groups.
6.8.2.1. Changing the binding names before projecting them into the workload

You can specify the rules to change the binding names in the .spec.namingStrategy attribute of the ServiceBinding CR. For example, consider a Spring PetClinic sample application that connects to the PostgreSQL database. In this case, the PostgreSQL database service exposes the host and port fields of the database to use for binding. The Spring PetClinic sample application can access this exposed binding data through the binding names.

Example: Spring PetClinic sample application in the ServiceBinding CR

# ...
    application:
      name: spring-petclinic
      group: apps
      version: v1
      resource: deployments
# ...

Example: PostgreSQL database service in the ServiceBinding CR

# ...
    services:
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo
# ...

If namingStrategy is not defined and the binding names are projected as environment variables, then the host: hippo-pgbouncer value in the backing service and the projected environment variable would appear as shown in the following example:

Example

DATABASE_HOST: hippo-pgbouncer

where:

DATABASE

Specifies the kind backend service.

HOST

Specifies the binding name.

After applying the POSTGRESQL_{{ .service.kind | upper }}_{{ .name | upper }}_ENV naming strategy, the list of custom binding names prepared by the service binding request appears as shown in the following example:

Example

POSTGRESQL_DATABASE_HOST_ENV: hippo-pgbouncer
POSTGRESQL_DATABASE_PORT_ENV: 5432

The following items describe the expressions defined in the POSTGRESQL_{{ .service.kind | upper }}_{{ .name | upper }}_ENV naming strategy:

  • .name: Refers to the binding name exposed by the backing service. In the previous example, the binding names are HOST and PORT.
  • .service.kind: Refers to the kind of service resource whose binding names are changed with the naming strategy.
  • upper: String function used to post-process the character string while compiling the Go template string.
  • POSTGRESQL: Prefix of the custom binding name.
  • ENV: Suffix of the custom binding name.

Similar to the previous example, you can define the string templates in namingStrategy to define how each key of the binding names should be prepared by the service binding request.

6.8.2.2. Composing custom binding data

As an application developer, you can compose custom binding data under the following circumstances:

  • The backing service does not expose binding data.
  • The values exposed are not available in the required format as expected by the workload.

For example, consider a case where the backing service CR exposes the host, port, and database user as binding data, but the workload requires that the binding data be consumed as a connection string. You can compose custom binding data using attributes in the Kubernetes resource representing the backing service.

Example

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
    name: spring-petclinic-pgcluster
    namespace: my-petclinic
spec:
    services:
    - group: postgres-operator.crunchydata.com
      version: v1beta1
      kind: PostgresCluster
      name: hippo 1
      id: postgresDB 2
    - group: ""
      version: v1
      kind: Secret
      name: hippo-pguser-hippo
      id: postgresSecret
    application:
      name: spring-petclinic
      group: apps
      version: v1
      resource: deployments
    mappings:
      ## From the database service
      - name: JDBC_URL
        value: 'jdbc:postgresql://{{ .postgresDB.metadata.annotations.proxy }}:{{ .postgresDB.spec.port }}/{{ .postgresDB.metadata.name }}'
      ## From both the services!
      - name: CREDENTIALS
        value: '{{ .postgresDB.metadata.name }}{{ translationService.postgresSecret.data.password }}'
      ## Generate JSON
      - name: DB_JSON 3
        value: {{ json .postgresDB.status }} 4

1
Name of the backing service resource.
2
Optional identifier.
3
The JSON name that the Service Binding Operator generates. The Service Binding Operator projects this JSON name as the name of a file or environment variable.
4
The JSON value that the Service Binding Operator generates. The Service Binding Operator projects this JSON value as a file or environment variable. The JSON value contains the attributes from your specified field of the backing service custom resource.
6.8.2.3. Binding workloads using a label selector

You can use a label selector to specify the workload to bind. If you declare a service binding using the label selectors to pick up workloads, the Service Binding Operator periodically attempts to find and bind new workloads that match the given label selector.

For example, as a cluster administrator, you can bind a service to every Deployment in a namespace with the environment: production label by setting an appropriate labelSelector field in the ServiceBinding CR. This enables the Service Binding Operator to bind each of these workloads with one ServiceBinding CR.

Example ServiceBinding CR in the binding.operators.coreos.com/v1alpha1 API

apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
  name: multi-application-binding
  namespace: service-binding-demo
spec:
  application:
    labelSelector: 1
      matchLabels:
        environment: production
    group: apps
    version: v1
    resource: deployments
  services:
    group: ""
    version: v1
    kind: Secret
    name: super-secret-data

1
Specifies the workload that is being bound.

Example ServiceBinding CR in the servicebinding.io API

apiVersion: servicebindings.io/v1beta1
kind: ServiceBinding
metadata:
  name: multi-application-binding
  namespace: service-binding-demo
spec:
  workload:
    selector: 1
      matchLabels:
        environment: production
    apiVersion: app/v1
    kind: Deployment
  service:
    apiVersion: v1
    kind: Secret
    name: super-secret-data

1
Specifies the workload that is being bound.
Important

If you define the following pairs of fields, Service Binding Operator refuses the binding operation and generates an error:

  • The name and labelSelector fields in the binding.operators.coreos.com/v1alpha1 API.
  • The name and selector fields in the servicebinding.io API (Spec API).

Understanding the rebinding behavior

Consider a case where, after a successful binding, you use the name field to identify a workload. If you delete and recreate that workload, the ServiceBinding reconciler does not rebind the workload, and the Operator cannot project the binding data to the workload. However, if you use the labelSelector field to identify a workload, the ServiceBinding reconciler rebinds the workload, and the Operator projects the binding data.

6.8.3. Binding secondary workloads that are not compliant with PodSpec

A typical scenario in service binding involves configuring the backing service, the workload (Deployment), and Service Binding Operator. Consider a scenario that involves a secondary workload (which can also be an application Operator) that is not compliant with PodSpec and is between the primary workload (Deployment) and Service Binding Operator.

For such secondary workload resources, the location of the container path is arbitrary. For service binding, if the secondary workload in a CR is not compliant with the PodSpec, you must specify the location of the container path. Doing so projects the binding data into the container path specified in the secondary workload of the ServiceBinding custom resource (CR), for example, when you do not want the binding data inside a pod.

In Service Binding Operator, you can configure the path of where containers or secrets reside within a workload and bind these paths at a custom location.

6.8.3.1. Configuring the custom location of the container path

This custom location is available for the binding.operators.coreos.com API group when Service Binding Operator projects the binding data as environment variables.

Consider a secondary workload CR, which is not compliant with the PodSpec and has containers located at the spec.containers path:

Example: Secondary workload CR

apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
    name: secondary-workload
spec:
    containers:
    - name: hello-world
      image: quay.io/baijum/secondary-workload:latest
      ports:
      - containerPort: 8080

Procedure

  • Configure the spec.containers path by specifying a value in the ServiceBinding CR and bind this path to a spec.application.bindingPath.containersPath custom location:

    Example: ServiceBinding CR with the spec.containers path in a custom location

    apiVersion: binding.operators.coreos.com/v1alpha1
    kind: ServiceBinding
    metadata:
        name: spring-petclinic-pgcluster
    spec:
        services:
        - group: postgres-operator.crunchydata.com
          version: v1beta1
          kind: PostgresCluster
          name: hippo
          id: postgresDB
        - group: ""
          version: v1
          kind: Secret
          name: hippo-pguser-hippo
          id: postgresSecret
        application: 1
          name: spring-petclinic
          group: apps
          version: v1
          resource: deployments
        application: 2
          name: secondary-workload
          group: operator.sbo.com
          version: v1
          resource: secondaryworkloads
          bindingPath:
            containersPath: spec.containers 3

    1
    The sample application that points to a Deployment or any other similar resource with an embedded PodSpec.
    2
    The secondary workload, which is not compliant with the PodSpec.
    3
    The custom location of the container path.

After you specify the location of the container path, Service Binding Operator generates the binding data, which becomes available in the container path specified in the secondary workload of the ServiceBinding CR.

The following example shows the spec.containers path with the envFrom and secretRef fields:

Example: Secondary workload CR with the envFrom and secretRef fields

apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
    name: secondary-workload
spec:
    containers:
    - env: 1
      - name: ServiceBindingOperatorChangeTriggerEnvVar
        value: "31793"
      envFrom:
      - secretRef:
          name: secret-resource-name 2
      image: quay.io/baijum/secondary-workload:latest
      name: hello-world
      ports:
      - containerPort: 8080
      resources: {}

1
Unique array of containers with values generated by the Service Binding Operator. These values are based on the backing service CR.
2
Name of the Secret resource generated by the Service Binding Operator.
6.8.3.2. Configuring the custom location of the secret path

This custom location is available for the binding.operators.coreos.com API group when Service Binding Operator projects the binding data as environment variables.

Consider a secondary workload CR, which is not compliant with the PodSpec, with only the secret at the spec.secret path:

Example: Secondary workload CR

apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
    name: secondary-workload
spec:
    secret: ""

Procedure

  • Configure the spec.secret path by specifying a value in the ServiceBinding CR and bind this path at a spec.application.bindingPath.secretPath custom location:

    Example: ServiceBinding CR with the spec.secret path in a custom location

    apiVersion: binding.operators.coreos.com/v1alpha1
    kind: ServiceBinding
    metadata:
        name: spring-petclinic-pgcluster
    spec:
    ...
        application: 1
          name: secondary-workload
          group: operator.sbo.com
          version: v1
          resource: secondaryworkloads
          bindingPath:
            secretPath: spec.secret 2
    ...

    1
    The secondary workload, which is not compliant with the PodSpec.
    2
    The custom location of the secret path that contains the name of the Secret resource.

After you specify the location of the secret path, Service Binding Operator generates the binding data, which becomes available in the secret path specified in the secondary workload of the ServiceBinding CR.

The following example shows the spec.secret path with the binding-request value:

Example: Secondary workload CR with the binding-request value

...
apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
    name: secondary-workload
spec:
    secret: binding-request-72ddc0c540ab3a290e138726940591debf14c581 1
...

1
The unique name of the Secret resource that Service Binding Operator generates.
6.8.3.3. Workload resource mapping
Note
  • Workload resource mapping is available for the secondary workloads of the ServiceBinding custom resource (CR) for both the API groups: binding.operators.coreos.com and servicebinding.io.
  • You must define ClusterWorkloadResourceMapping resources only under the servicebinding.io API group. However, the ClusterWorkloadResourceMapping resources interact with ServiceBinding resources under both the binding.operators.coreos.com and servicebinding.io API groups.

If you cannot configure custom path locations by using the configuration method for container path, you can define exactly where binding data needs to be projected. Specify where to project the binding data for a given workload kind by defining the ClusterWorkloadResourceMapping resources in the servicebinding.io API group.

The following example shows how to define a mapping for the CronJob.batch/v1 resources.

Example: Mapping for CronJob.batch/v1 resources

apiVersion: servicebinding.io/v1beta1
kind: ClusterWorkloadResourceMapping
metadata:
 name: cronjobs.batch 1
spec:
  versions:
  - version: "v1" 2
    annotations: .spec.jobTemplate.spec.template.metadata.annotations 3
    containers:
    - path: .spec.jobTemplate.spec.template.spec.containers[*] 4
    - path: .spec.jobTemplate.spec.template.spec.initContainers[*]
      name: .name 5
      env: .env 6
      volumeMounts: .volumeMounts 7
    volumes: .spec.jobTemplate.spec.template.spec.volumes 8

1
Name of the ClusterWorkloadResourceMapping resource, which must be qualified as the plural.group of the mapped workload resource.
2
Version of the resource that is being mapped. Any version that is not specified can be matched with the "*" wildcard.
3
Optional: Identifier of the .annotations field in a pod, specified with a fixed JSONPath. The default value is .spec.template.spec.annotations.
4
Identifier of the .containers and .initContainers fields in a pod, specified with a JSONPath. If no entries under the containers field are defined, the Service Binding Operator defaults to two paths: .spec.template.spec.containers[*] and .spec.template.spec.initContainers[\*], with all other fields set as their default. However, if you specify an entry, then you must define the .path field.
5
Optional: Identifier of the .name field in a container, specified with a fixed JSONPath. The default value is .name.
6
Optional: Identifier of the .env field in a container, specified with a fixed JSONPath. The default value is .env.
7
Optional: Identifier of the .volumeMounts field in a container, specified with a fixed JSONPath. The default value is .volumeMounts.
8
Optional: Identifier of the .volumes field in a pod, specified with a fixed JSONPath. The default value is .spec.template.spec.volumes.
Important
  • In this context, a fixed JSONPath is a subset of the JSONPath grammar that accepts only the following operations:

    • Field lookup: .spec.template
    • Array indexing: .spec['template']

    All other operations are not accepted.

  • Most of these fields are optional. When they are not specified, the Service Binding Operator assumes defaults compatible with PodSpec resources.
  • The Service Binding Operator requires that each of these fields is structurally equivalent to the corresponding field in a pod deployment. For example, the contents of the .env field in a workload resource must be able to accept the same structure of data that the .env field in a Pod resource would. Otherwise, projecting binding data into such a workload might result in unexpected behavior from the Service Binding Operator.

Behavior specific to the binding.operators.coreos.com API group

You can expect the following behaviors when ClusterWorkloadResourceMapping resources interact with ServiceBinding resources under the binding.operators.coreos.com API group:

  • If a ServiceBinding resource with the bindAsFiles: false flag value is created together with one of these mappings, then environment variables are projected into the .envFrom field underneath each path field specified in the corresponding ClusterWorkloadResourceMapping resource.
  • As a cluster administrator, you can specify both a ClusterWorkloadResourceMapping resource and the .spec.application.bindingPath.containersPath field in a ServiceBinding.bindings.coreos.com resource for binding purposes.

    The Service Binding Operator attempts to project binding data into the locations specified in both a ClusterWorkloadResourceMapping resource and the .spec.application.bindingPath.containersPath field. This behavior is equivalent to adding a container entry to the corresponding ClusterWorkloadResourceMapping resource with the path: $containersPath attribute, with all other values taking their default value.

6.8.4. Unbinding workloads from a backing service

You can unbind a workload from a backing service by using the oc tool.

  • To unbind a workload from a backing service, delete the ServiceBinding custom resource (CR) linked to it:

    $ oc delete ServiceBinding <.metadata.name>

    Example

    $ oc delete ServiceBinding spring-petclinic-pgcluster

    where:

    spring-petclinic-pgcluster

    Specifies the name of the ServiceBinding CR.

6.8.5. Additional resources

6.9. Connecting an application to a service using the Developer perspective

Use the Topology view for the following purposes:

  • Grouping multiple components within an application.
  • Connecting components with each other.
  • Connecting multiple resources to services with labels.

You can either use a binding or a visual connector to connect components.

A binding connection between the components can be established only if the target node is an Operator-backed service. This is indicated by the Create a binding connector tool-tip which appears when you drag an arrow to such a target node. When an application is connected to a service by using a binding connector a ServiceBinding resource is created. Then, the Service Binding Operator controller projects the necessary binding data into the application deployment. After the request is successful, the application is redeployed establishing an interaction between the connected components.

A visual connector establishes only a visual connection between the components, depicting an intent to connect. No interaction between the components is established. If the target node is not an Operator-backed service the Create a visual connector tool-tip is displayed when you drag an arrow to a target node.

6.9.1. Discovering and identifying Operator-backed bindable services

As a user, if you want to create a bindable service, you must know which services are bindable. Bindable services are services that the applications can consume easily because they expose their binding data such as credentials, connection details, volume mounts, secrets, and other binding data in a standard way. The Developer perspective helps you discover and identify such bindable services.

Procedure

  • To discover and identify Operator-backed bindable services, consider the following alternative approaches:

    • Click +AddDeveloper CatalogOperator Backed to see the Operator-backed tiles. Operator-backed services that support service binding features have a Bindable badge on the tiles.
    • On the left pane of the Operator Backed page, select Bindable.

      Tip

      Click the help icon next to Service binding to see more information about bindable services.

    • Click +AddAdd and search for Operator-backed services. When you click the bindable service, you can view the Bindable badge in the side panel.

6.9.2. Creating a visual connection between components

You can depict an intent to connect application components by using the visual connector.

This procedure walks you through an example of creating a visual connection between a PostgreSQL Database service and a Spring PetClinic sample application.

Prerequisites

  • You have created and deployed a Spring PetClinic sample application by using the Developer perspective.
  • You have created and deployed a Crunchy PostgreSQL database instance by using the Developer perspective. This instance has the following components: hippo-backup, hippo-instance, hippo-repo-host, and hippo-pgbouncer.

Procedure

  1. In the Developer perspective, switch to the relevant project, for example, my-petclinic.
  2. Hover over the Spring PetClinic sample application to see a dangling arrow on the node.

    Figure 6.2. Visual connector

    odc connector
  3. Click and drag the arrow towards the hippo-pgbouncer deployment to connect the Spring PetClinic sample application with it.
  4. Click the spring-petclinic deployment to see the Overview panel. Under the Details tab, click the edit icon in the Annotations section to see the Key = app.openshift.io/connects-to and Value = [{"apiVersion":"apps/v1","kind":"Deployment","name":"hippo-pgbouncer"}] annotation added to the deployment.
  5. Optional: You can repeat these steps to establish visual connections between other applications and components you create.

    Figure 6.3. Connecting multiple applications

    odc connecting multiple applications

6.9.3. Creating a binding connection between components

You can create a binding connection with Operator-backed components, as demonstrated in the following example, which uses a PostgreSQL Database service and a Spring PetClinic sample application. To create a binding connection with a service that the PostgreSQL Database Operator backs, you must first add the Red Hat-provided PostgreSQL Database Operator to the OperatorHub, and then install the Operator. The PostreSQL Database Operator then creates and manages the Database resource, which exposes the binding data in secrets, config maps, status, and spec attributes.

Prerequisites

  • You created and deployed a Spring PetClinic sample application in the Developer perspective.
  • You installed Service Binding Operator from the OperatorHub.
  • You installed the Crunchy Postgres for Kubernetes Operator from the OperatorHub in the v5 Update channel.
  • You created a PostgresCluster resource in the Developer perspective, which resulted in a Crunchy PostgreSQL database instance with the following components: hippo-backup, hippo-instance, hippo-repo-host, and hippo-pgbouncer.

Procedure

  1. In the Developer perspective, switch to the relevant project, for example, my-petclinic.
  2. In the Topology view, hover over the Spring PetClinic sample application to see a dangling arrow on the node.
  3. Drag and drop the arrow onto the hippo database icon in the Postgres Cluster to make a binding connection with the Spring PetClinic sample application.
  4. In the Create Service Binding dialog, keep the default name or add a different name for the service binding, and then click Create.

    Figure 6.4. Service Binding dialog

    odc sbc modal
  5. Optional: If there is difficulty in making a binding connection using the Topology view, go to +AddYAMLImport YAML.
  6. Optional: In the YAML editor, add the ServiceBinding resource:

    apiVersion: binding.operators.coreos.com/v1alpha1
    kind: ServiceBinding
    metadata:
        name: spring-petclinic-pgcluster
        namespace: my-petclinic
    spec:
        services:
        - group: postgres-operator.crunchydata.com
          version: v1beta1
          kind: PostgresCluster
          name: hippo
        application:
          name: spring-petclinic
          group: apps
          version: v1
          resource: deployments

    A service binding request is created and a binding connection is created through a ServiceBinding resource. When the database service connection request succeeds, the application is redeployed and the connection is established.

    Figure 6.5. Binding connector

    odc binding connector
    Tip

    You can also use the context menu by dragging the dangling arrow to add and create a binding connection to an operator-backed service.

    Figure 6.6. Context menu to create binding connection

    odc context operator
  7. In the navigation menu, click Topology. The spring-petclinic deployment in the Topology view includes an Open URL link to view its web page.
  8. Click the Open URL link.

You can now view the Spring PetClinic sample application remotely to confirm that the application is now connected to the database service and that the data has been successfully projected to the application from the Crunchy PostgreSQL database service.

The Service Binding Operator has successfully created a working connection between the application and the database service.

6.9.4. Verifying the status of your service binding from the Topology view

The Developer perspective helps you verify the status of your service binding through the Topology view.

Procedure

  1. If a service binding was successful, click the binding connector. A side panel appears displaying the Connected status under the Details tab.

    Optionally, you can view the Connected status on the following pages from the Developer perspective:

    • The ServiceBindings page.
    • The ServiceBinding details page. In addition, the page title displays a Connected badge.
  2. If a service binding was unsuccessful, the binding connector shows a red arrowhead and a red cross in the middle of the connection. Click this connector to view the Error status in the side panel under the Details tab. Optionally, click the Error status to view specific information about the underlying problem.

    You can also view the Error status and a tooltip on the following pages from the Developer perspective:

    • The ServiceBindings page.
    • The ServiceBinding details page. In addition, the page title displays an Error badge.
Tip

In the ServiceBindings page, use the Filter dropdown to list the service bindings based on their status.

6.9.5. Visualizing the binding connections to resources

As a user, use Label Selector in the Topology view to visualize a service binding and simplify the process of binding applications to backing services. When creating ServiceBinding resources, specify labels by using Label Selector to find and connect applications instead of using the name of the application. The Service Binding Operator then consumes these ServiceBinding resources and specified labels to find the applications to create a service binding with.

Tip

To navigate to a list of all connected resources, click the label selector associated with the ServiceBinding resource.

To view the Label Selector, consider the following approaches:

  • After you import a ServiceBinding resource, view the Label Selector associated with the service binding on the ServiceBinding details page.

    Figure 6.7. ServiceBinding details page

    odc label selector sb details
Note

To use Label Selector and to create one or more connections at once, you must import the YAML file of the ServiceBinding resource.

  • After the connection is established and when you click the binding connector, the service binding connector Details side panel appears. You can view the Label Selector associated with the service binding on this panel.

    Figure 6.8. Topology label selector side panel

    odc label selector topology side panel
    Note

    When you delete a binding connector (a single connection within Topology along with a service binding), the action removes all connections that are tied to the deleted service binding. While deleting a binding connector, a confirmation dialog appears, which informs that all connectors will be deleted.

    Figure 6.9. Delete ServiceBinding confirmation dialog

    odc delete service binding

6.9.6. Additional resources

Chapter 7. Working with Helm charts

7.1. Understanding Helm

Helm is a software package manager that simplifies deployment of applications and services to OpenShift Container Platform clusters.

Helm uses a packaging format called charts. A Helm chart is a collection of files that describes the OpenShift Container Platform resources.

Creating a chart in a cluster creates a running instance of the chart known as a release.

Each time a chart is created, or a release is upgraded or rolled back, an incremental revision is created.

7.1.1. Key features

Helm provides the ability to:

  • Search through a large collection of charts stored in the chart repository.
  • Modify existing charts.
  • Create your own charts with OpenShift Container Platform or Kubernetes resources.
  • Package and share your applications as charts.

7.1.2. Red Hat Certification of Helm charts for OpenShift

You can choose to verify and certify your Helm charts by Red Hat for all the components you will be deploying on the Red Hat OpenShift Container Platform. Charts go through an automated Red Hat OpenShift certification workflow that guarantees security compliance as well as best integration and experience with the platform. Certification assures the integrity of the chart and ensures that the Helm chart works seamlessly on Red Hat OpenShift clusters.

7.1.3. Additional resources

7.2. Installing Helm

The following section describes how to install Helm on different platforms using the CLI.

You can also find the URL to the latest binaries from the OpenShift Container Platform web console by clicking the ? icon in the upper-right corner and selecting Command Line Tools.

Prerequisites

  • You have installed Go, version 1.13 or higher.

7.2.1. On Linux

  1. Download the Helm binary and add it to your path:

    • Linux (x86_64, amd64)

      # curl -L https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest/helm-linux-amd64 -o /usr/local/bin/helm
    • Linux on IBM Z and IBM® LinuxONE (s390x)

      # curl -L https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest/helm-linux-s390x -o /usr/local/bin/helm
    • Linux on IBM Power (ppc64le)

      # curl -L https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest/helm-linux-ppc64le -o /usr/local/bin/helm
  2. Make the binary file executable:

    # chmod +x /usr/local/bin/helm
  3. Check the installed version:

    $ helm version

    Example output

    version.BuildInfo{Version:"v3.0", GitCommit:"b31719aab7963acf4887a1c1e6d5e53378e34d93", GitTreeState:"clean", GoVersion:"go1.13.4"}

7.2.2. On Windows 7/8

  1. Download the latest .exe file and put in a directory of your preference.
  2. Right click Start and click Control Panel.
  3. Select System and Security and then click System.
  4. From the menu on the left, select Advanced systems settings and click Environment Variables at the bottom.
  5. Select Path from the Variable section and click Edit.
  6. Click New and type the path to the folder with the .exe file into the field or click Browse and select the directory, and click OK.

7.2.3. On Windows 10

  1. Download the latest .exe file and put in a directory of your preference.
  2. Click Search and type env or environment.
  3. Select Edit environment variables for your account.
  4. Select Path from the Variable section and click Edit.
  5. Click New and type the path to the directory with the exe file into the field or click Browse and select the directory, and click OK.

7.2.4. On MacOS

  1. Download the Helm binary and add it to your path:

    # curl -L https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest/helm-darwin-amd64 -o /usr/local/bin/helm
  2. Make the binary file executable:

    # chmod +x /usr/local/bin/helm
  3. Check the installed version:

    $ helm version

    Example output

    version.BuildInfo{Version:"v3.0", GitCommit:"b31719aab7963acf4887a1c1e6d5e53378e34d93", GitTreeState:"clean", GoVersion:"go1.13.4"}

7.3. Configuring custom Helm chart repositories

You can create Helm releases on an OpenShift Container Platform cluster using the following methods:

  • The CLI.
  • The Developer perspective of the web console.

The Developer Catalog, in the Developer perspective of the web console, displays the Helm charts available in the cluster. By default, it lists the Helm charts from the Red Hat OpenShift Helm chart repository. For a list of the charts, see the Red Hat Helm index file.

As a cluster administrator, you can add multiple cluster-scoped and namespace-scoped Helm chart repositories, separate from the default cluster-scoped Helm repository, and display the Helm charts from these repositories in the Developer Catalog.

As a regular user or project member with the appropriate role-based access control (RBAC) permissions, you can add multiple namespace-scoped Helm chart repositories, apart from the default cluster-scoped Helm repository, and display the Helm charts from these repositories in the Developer Catalog.

In the Developer perspective of the web console, you can use the Helm page to:

  • Create Helm Releases and Repositories using the Create button.
  • Create, update, or delete a cluster-scoped or namespace-scoped Helm chart repository.
  • View the list of the existing Helm chart repositories in the Repositories tab, which can also be easily distinguished as either cluster scoped or namespace scoped.

7.3.1. Installing a Helm chart on an OpenShift Container Platform cluster

Prerequisites

  • You have a running OpenShift Container Platform cluster and you have logged into it.
  • You have installed Helm.

Procedure

  1. Create a new project:

    $ oc new-project vault
  2. Add a repository of Helm charts to your local Helm client:

    $ helm repo add openshift-helm-charts https://charts.openshift.io/

    Example output

    "openshift-helm-charts" has been added to your repositories

  3. Update the repository:

    $ helm repo update
  4. Install an example HashiCorp Vault:

    $ helm install example-vault openshift-helm-charts/hashicorp-vault

    Example output

    NAME: example-vault
    LAST DEPLOYED: Fri Mar 11 12:02:12 2022
    NAMESPACE: vault
    STATUS: deployed
    REVISION: 1
    NOTES:
    Thank you for installing HashiCorp Vault!

  5. Verify that the chart has installed successfully:

    $ helm list

    Example output

    NAME         	NAMESPACE	REVISION	UPDATED                                	STATUS  	CHART       	APP VERSION
    example-vault	vault    	1       	2022-03-11 12:02:12.296226673 +0530 IST	deployed	vault-0.19.0	1.9.2

7.3.2. Creating Helm releases using the Developer perspective

You can use either the Developer perspective in the web console or the CLI to select and create a release from the Helm charts listed in the Developer Catalog. You can create Helm releases by installing Helm charts and see them in the Developer perspective of the web console.

Prerequisites

Procedure

To create Helm releases from the Helm charts provided in the Developer Catalog:

  1. In the Developer perspective, navigate to the +Add view and select a project. Then click Helm Chart option to see all the Helm Charts in the Developer Catalog.
  2. Select a chart and read the description, README, and other details about the chart.
  3. Click Create.

    Figure 7.1. Helm charts in developer catalog

    odc helm chart devcatalog new
  4. In the Create Helm Release page:

    1. Enter a unique name for the release in the Release Name field.
    2. Select the required chart version from the Chart Version drop-down list.
    3. Configure your Helm chart by using the Form View or the YAML View.

      Note

      Where available, you can switch between the YAML View and Form View. The data is persisted when switching between the views.

    4. Click Create to create a Helm release. The web console displays the new release in the Topology view.

      If a Helm chart has release notes, the web console displays them.

      If a Helm chart creates workloads, the web console displays them on the Topology or Helm release details page. The workloads are DaemonSet, CronJob, Pod, Deployment, and DeploymentConfig.

    5. View the newly created Helm release in the Helm Releases page.

You can upgrade, rollback, or delete a Helm release by using the Actions button on the side panel or by right-clicking a Helm release.

7.3.3. Using Helm in the web terminal

You can use Helm by Accessing the web terminal in the Developer perspective of the web console.

7.3.4. Creating a custom Helm chart on OpenShift Container Platform

Procedure

  1. Create a new project:

    $ oc new-project nodejs-ex-k
  2. Download an example Node.js chart that contains OpenShift Container Platform objects:

    $ git clone https://github.com/redhat-developer/redhat-helm-charts
  3. Go to the directory with the sample chart:

    $ cd redhat-helm-charts/alpha/nodejs-ex-k/
  4. Edit the Chart.yaml file and add a description of your chart:

    apiVersion: v2 1
    name: nodejs-ex-k 2
    description: A Helm chart for OpenShift 3
    icon: https://static.redhat.com/libs/redhat/brand-assets/latest/corp/logo.svg 4
    version: 0.2.1 5
    1
    The chart API version. It should be v2 for Helm charts that require at least Helm 3.
    2
    The name of your chart.
    3
    The description of your chart.
    4
    The URL to an image to be used as an icon.
    5
    The Version of your chart as per the Semantic Versioning (SemVer) 2.0.0 Specification.
  5. Verify that the chart is formatted properly:

    $ helm lint

    Example output

    [INFO] Chart.yaml: icon is recommended
    
    1 chart(s) linted, 0 chart(s) failed

  6. Navigate to the previous directory level:

    $ cd ..
  7. Install the chart:

    $ helm install nodejs-chart nodejs-ex-k
  8. Verify that the chart has installed successfully:

    $ helm list

    Example output

    NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
    nodejs-chart nodejs-ex-k 1 2019-12-05 15:06:51.379134163 -0500 EST deployed nodejs-0.1.0  1.16.0

7.3.5. Adding custom Helm chart repositories

As a cluster administrator, you can add custom Helm chart repositories to your cluster and enable access to the Helm charts from these repositories in the Developer Catalog.

Procedure

  1. To add a new Helm Chart Repository, you must add the Helm Chart Repository custom resource (CR) to your cluster.

    Sample Helm Chart Repository CR

    apiVersion: helm.openshift.io/v1beta1
    kind: HelmChartRepository
    metadata:
      name: <name>
    spec:
     # optional name that might be used by console
     # name: <chart-display-name>
      connectionConfig:
        url: <helm-chart-repository-url>

    For example, to add an Azure sample chart repository, run:

    $ cat <<EOF | oc apply -f -
    apiVersion: helm.openshift.io/v1beta1
    kind: HelmChartRepository
    metadata:
      name: azure-sample-repo
    spec:
      name: azure-sample-repo
      connectionConfig:
        url: https://raw.githubusercontent.com/Azure-Samples/helm-charts/master/docs
    EOF
  2. Navigate to the Developer Catalog in the web console to verify that the Helm charts from the chart repository are displayed.

    For example, use the Chart repositories filter to search for a Helm chart from the repository.

    Figure 7.2. Chart repositories filter

    odc helm chart repo filter
    Note

    If a cluster administrator removes all of the chart repositories, then you cannot view the Helm option in the +Add view, Developer Catalog, and left navigation panel.

7.3.6. Adding namespace-scoped custom Helm chart repositories

The cluster-scoped HelmChartRepository custom resource definition (CRD) for Helm repository provides the ability for administrators to add Helm repositories as custom resources. The namespace-scoped ProjectHelmChartRepository CRD allows project members with the appropriate role-based access control (RBAC) permissions to create Helm repository resources of their choice but scoped to their namespace. Such project members can see charts from both cluster-scoped and namespace-scoped Helm repository resources.

Note
  • Administrators can limit users from creating namespace-scoped Helm repository resources. By limiting users, administrators have the flexibility to control the RBAC through a namespace role instead of a cluster role. This avoids unnecessary permission elevation for the user and prevents access to unauthorized services or applications.
  • The addition of the namespace-scoped Helm repository does not impact the behavior of the existing cluster-scoped Helm repository.

As a regular user or project member with the appropriate RBAC permissions, you can add custom namespace-scoped Helm chart repositories to your cluster and enable access to the Helm charts from these repositories in the Developer Catalog.

Procedure

  1. To add a new namespace-scoped Helm Chart Repository, you must add the Helm Chart Repository custom resource (CR) to your namespace.

    Sample Namespace-scoped Helm Chart Repository CR

    apiVersion: helm.openshift.io/v1beta1
    kind: ProjectHelmChartRepository
    metadata:
      name: <name>
    spec:
      url: https://my.chart-repo.org/stable
    
      # optional name that might be used by console
      name: <chart-repo-display-name>
    
      # optional and only needed for UI purposes
      description: <My private chart repo>
    
      # required: chart repository URL
      connectionConfig:
        url: <helm-chart-repository-url>

    For example, to add an Azure sample chart repository scoped to your my-namespace namespace, run:

    $ cat <<EOF | oc apply --namespace my-namespace -f -
    apiVersion: helm.openshift.io/v1beta1
    kind: ProjectHelmChartRepository
    metadata:
      name: azure-sample-repo
    spec:
      name: azure-sample-repo
      connectionConfig:
        url: https://raw.githubusercontent.com/Azure-Samples/helm-charts/master/docs
    EOF

    The output verifies that the namespace-scoped Helm Chart Repository CR is created:

    Example output

    projecthelmchartrepository.helm.openshift.io/azure-sample-repo created

  2. Navigate to the Developer Catalog in the web console to verify that the Helm charts from the chart repository are displayed in your my-namespace namespace.

    For example, use the Chart repositories filter to search for a Helm chart from the repository.

    Figure 7.3. Chart repositories filter in your namespace

    odc namespace helm chart repo filter

    Alternatively, run:

    $ oc get projecthelmchartrepositories --namespace my-namespace

    Example output

    NAME                     AGE
    azure-sample-repo        1m

    Note

    If a cluster administrator or a regular user with appropriate RBAC permissions removes all of the chart repositories in a specific namespace, then you cannot view the Helm option in the +Add view, Developer Catalog, and left navigation panel for that specific namespace.

7.3.7. Creating credentials and CA certificates to add Helm chart repositories

Some Helm chart repositories need credentials and custom certificate authority (CA) certificates to connect to it. You can use the web console as well as the CLI to add credentials and certificates.

Procedure

To configure the credentials and certificates, and then add a Helm chart repository using the CLI:

  1. In the openshift-config namespace, create a ConfigMap object with a custom CA certificate in PEM encoded format, and store it under the ca-bundle.crt key within the config map:

    $ oc create configmap helm-ca-cert \
    --from-file=ca-bundle.crt=/path/to/certs/ca.crt \
    -n openshift-config
  2. In the openshift-config namespace, create a Secret object to add the client TLS configurations:

    $ oc create secret tls helm-tls-configs \
    --cert=/path/to/certs/client.crt \
    --key=/path/to/certs/client.key \
    -n openshift-config

    Note that the client certificate and key must be in PEM encoded format and stored under the keys tls.crt and tls.key, respectively.

  3. Add the Helm repository as follows:

    $ cat <<EOF | oc apply -f -
    apiVersion: helm.openshift.io/v1beta1
    kind: HelmChartRepository
    metadata:
      name: <helm-repository>
    spec:
      name: <helm-repository>
      connectionConfig:
        url: <URL for the Helm repository>
        tlsConfig:
            name: helm-tls-configs
        ca:
    	name: helm-ca-cert
    EOF

    The ConfigMap and Secret are consumed in the HelmChartRepository CR using the tlsConfig and ca fields. These certificates are used to connect to the Helm repository URL.

  4. By default, all authenticated users have access to all configured charts. However, for chart repositories where certificates are needed, you must provide users with read access to the helm-ca-cert config map and helm-tls-configs secret in the openshift-config namespace, as follows:

    $ cat <<EOF | kubectl apply -f -
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      namespace: openshift-config
      name: helm-chartrepos-tls-conf-viewer
    rules:
    - apiGroups: [""]
      resources: ["configmaps"]
      resourceNames: ["helm-ca-cert"]
      verbs: ["get"]
    - apiGroups: [""]
      resources: ["secrets"]
      resourceNames: ["helm-tls-configs"]
      verbs: ["get"]
    ---
    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      namespace: openshift-config
      name: helm-chartrepos-tls-conf-viewer
    subjects:
      - kind: Group
        apiGroup: rbac.authorization.k8s.io
        name: 'system:authenticated'
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: helm-chartrepos-tls-conf-viewer
    EOF

7.3.8. Filtering Helm Charts by their certification level

You can filter Helm charts based on their certification level in the Developer Catalog.

Procedure

  1. In the Developer perspective, navigate to the +Add view and select a project.
  2. From the Developer Catalog tile, select the Helm Chart option to see all the Helm charts in the Developer Catalog.
  3. Use the filters to the left of the list of Helm charts to filter the required charts:

    • Use the Chart Repositories filter to filter charts provided by Red Hat Certification Charts or OpenShift Helm Charts.
    • Use the Source filter to filter charts sourced from Partners, Community, or Red Hat. Certified charts are indicated with the ( odc verified icon ) icon.
Note

The Source filter will not be visible when there is only one provider type.

You can now select the required chart and install it.

7.3.9. Disabling Helm Chart repositories

You can disable Helm Charts from a particular Helm Chart Repository in the catalog by setting the disabled property in the HelmChartRepository custom resource to true.

Procedure

  • To disable a Helm Chart repository by using CLI, add the disabled: true flag to the custom resource. For example, to remove an Azure sample chart repository, run:

    $ cat <<EOF | oc apply -f -
    apiVersion: helm.openshift.io/v1beta1
    kind: HelmChartRepository
    metadata:
      name: azure-sample-repo
    spec:
      connectionConfig:
       url:https://raw.githubusercontent.com/Azure-Samples/helm-charts/master/docs
      disabled: true
    EOF
  • To disable a recently added Helm Chart repository by using Web Console:

    1. Go to Custom Resource Definitions and search for the HelmChartRepository custom resource.
    2. Go to Instances, find the repository you want to disable, and click its name.
    3. Go to the YAML tab, add the disabled: true flag in the spec section, and click Save.

      Example

      spec:
        connectionConfig:
          url: <url-of-the-repositoru-to-be-disabled>
        disabled: true

      The repository is now disabled and will not appear in the catalog.

7.4. Working with Helm releases

You can use the Developer perspective in the web console to update, rollback, or delete a Helm release.

7.4.1. Prerequisites

7.4.2. Upgrading a Helm release

You can upgrade a Helm release to upgrade to a new chart version or update your release configuration.

Procedure

  1. In the Topology view, select the Helm release to see the side panel.
  2. Click ActionsUpgrade Helm Release.
  3. In the Upgrade Helm Release page, select the Chart Version you want to upgrade to, and then click Upgrade to create another Helm release. The Helm Releases page displays the two revisions.

7.4.3. Rolling back a Helm release

If a release fails, you can rollback the Helm release to a previous version.

Procedure

To rollback a release using the Helm view:

  1. In the Developer perspective, navigate to the Helm view to see the Helm Releases in the namespace.
  2. Click the Options menu kebab adjoining the listed release, and select Rollback.
  3. In the Rollback Helm Release page, select the Revision you want to rollback to and click Rollback.
  4. In the Helm Releases page, click on the chart to see the details and resources for that release.
  5. Go to the Revision History tab to see all the revisions for the chart.

    Figure 7.4. Helm revision history

    odc helm revision history
  6. If required, you can further use the Options menu kebab adjoining a particular revision and select the revision to rollback to.

7.4.4. Deleting a Helm release

Procedure

  1. In the Topology view, right-click the Helm release and select Delete Helm Release.
  2. In the confirmation prompt, enter the name of the chart and click Delete.

Chapter 8. Deployments

8.1. Understanding Deployment and DeploymentConfig objects

The Deployment and DeploymentConfig API objects in OpenShift Container Platform provide two similar but different methods for fine-grained management over common user applications. They are composed of the following separate API objects:

  • A Deployment or DeploymentConfig object, either of which describes the desired state of a particular component of the application as a pod template.
  • Deployment objects involve one or more replica sets, which contain a point-in-time record of the state of a deployment as a pod template. Similarly, DeploymentConfig objects involve one or more replication controllers, which preceded replica sets.
  • One or more pods, which represent an instance of a particular version of an application.

Use Deployment objects unless you need a specific feature or behavior provided by DeploymentConfig objects.

8.1.1. Building blocks of a deployment

Deployments and deployment configs are enabled by the use of native Kubernetes API objects ReplicaSet and ReplicationController, respectively, as their building blocks.

Users do not have to manipulate replica sets, replication controllers, or pods owned by Deployment or DeploymentConfig objects. The deployment systems ensure changes are propagated appropriately.

Tip

If the existing deployment strategies are not suited for your use case and you must run manual steps during the lifecycle of your deployment, then you should consider creating a custom deployment strategy.

The following sections provide further details on these objects.

8.1.1.1. Replica sets

A ReplicaSet is a native Kubernetes API object that ensures a specified number of pod replicas are running at any given time.

Note

Only use replica sets if you require custom update orchestration or do not require updates at all. Otherwise, use deployments. Replica sets can be used independently, but are used by deployments to orchestrate pod creation, deletion, and updates. Deployments manage their replica sets automatically, provide declarative updates to pods, and do not have to manually manage the replica sets that they create.

The following is an example ReplicaSet definition:

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: frontend-1
  labels:
    tier: frontend
spec:
  replicas: 3
  selector: 1
    matchLabels: 2
      tier: frontend
    matchExpressions: 3
      - {key: tier, operator: In, values: [frontend]}
  template:
    metadata:
      labels:
        tier: frontend
    spec:
      containers:
      - image: openshift/hello-openshift
        name: helloworld
        ports:
        - containerPort: 8080
          protocol: TCP
      restartPolicy: Always
1
A label query over a set of resources. The result of matchLabels and matchExpressions are logically conjoined.
2
Equality-based selector to specify resources with labels that match the selector.
3
Set-based selector to filter keys. This selects all resources with key equal to tier and value equal to frontend.
8.1.1.2. Replication controllers

Similar to a replica set, a replication controller ensures that a specified number of replicas of a pod are running at all times. If pods exit or are deleted, the replication controller instantiates more up to the defined number. Likewise, if there are more running than desired, it deletes as many as necessary to match the defined amount. The difference between a replica set and a replication controller is that a replica set supports set-based selector requirements whereas a replication controller only supports equality-based selector requirements.

A replication controller configuration consists of:

  • The number of replicas desired, which can be adjusted at run time.
  • A Pod definition to use when creating a replicated pod.
  • A selector for identifying managed pods.

A selector is a set of labels assigned to the pods that are managed by the replication controller. These labels are included in the Pod definition that the replication controller instantiates. The replication controller uses the selector to determine how many instances of the pod are already running in order to adjust as needed.

The replication controller does not perform auto-scaling based on load or traffic, as it does not track either. Rather, this requires its replica count to be adjusted by an external auto-scaler.

Note

Use a DeploymentConfig to create a replication controller instead of creating replication controllers directly.

If you require custom orchestration or do not require updates, use replica sets instead of replication controllers.

The following is an example definition of a replication controller:

apiVersion: v1
kind: ReplicationController
metadata:
  name: frontend-1
spec:
  replicas: 1  1
  selector:    2
    name: frontend
  template:    3
    metadata:
      labels:  4
        name: frontend 5
    spec:
      containers:
      - image: openshift/hello-openshift
        name: helloworld
        ports:
        - containerPort: 8080
          protocol: TCP
      restartPolicy: Always
1
The number of copies of the pod to run.
2
The label selector of the pod to run.
3
A template for the pod the controller creates.
4
Labels on the pod should include those from the label selector.
5
The maximum name length after expanding any parameters is 63 characters.

8.1.2. Deployments

Kubernetes provides a first-class, native API object type in OpenShift Container Platform called Deployment. Deployment objects describe the desired state of a particular component of an application as a pod template. Deployments create replica sets, which orchestrate pod lifecycles.

For example, the following deployment definition creates a replica set to bring up one hello-openshift pod:

Deployment definition

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-openshift
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello-openshift
  template:
    metadata:
      labels:
        app: hello-openshift
    spec:
      containers:
      - name: hello-openshift
        image: openshift/hello-openshift:latest
        ports:
        - containerPort: 80

8.1.3. DeploymentConfig objects

Building on replication controllers, OpenShift Container Platform adds expanded support for the software development and deployment lifecycle with the concept of DeploymentConfig objects. In the simplest case, a DeploymentConfig object creates a new replication controller and lets it start up pods.

However, OpenShift Container Platform deployments from DeploymentConfig objects also provide the ability to transition from an existing deployment of an image to a new one and also define hooks to be run before or after creating the replication controller.

The DeploymentConfig deployment system provides the following capabilities:

  • A DeploymentConfig object, which is a template for running applications.
  • Triggers that drive automated deployments in response to events.
  • User-customizable deployment strategies to transition from the previous version to the new version. A strategy runs inside a pod commonly referred as the deployment process.
  • A set of hooks (lifecycle hooks) for executing custom behavior in different points during the lifecycle of a deployment.
  • Versioning of your application to support rollbacks either manually or automatically in case of deployment failure.
  • Manual replication scaling and autoscaling.

When you create a DeploymentConfig object, a replication controller is created representing the DeploymentConfig object’s pod template. If the deployment changes, a new replication controller is created with the latest pod template, and a deployment process runs to scale down the old replication controller and scale up the new one.

Instances of your application are automatically added and removed from both service load balancers and routers as they are created. As long as your application supports graceful shutdown when it receives the TERM signal, you can ensure that running user connections are given a chance to complete normally.

The OpenShift Container Platform DeploymentConfig object defines the following details:

  1. The elements of a ReplicationController definition.
  2. Triggers for creating a new deployment automatically.
  3. The strategy for transitioning between deployments.
  4. Lifecycle hooks.

Each time a deployment is triggered, whether manually or automatically, a deployer pod manages the deployment (including scaling down the old replication controller, scaling up the new one, and running hooks). The deployment pod remains for an indefinite amount of time after it completes the deployment to retain its logs of the deployment. When a deployment is superseded by another, the previous replication controller is retained to enable easy rollback if needed.

Example DeploymentConfig definition

apiVersion: apps.openshift.io/v1
kind: DeploymentConfig
metadata:
  name: frontend
spec:
  replicas: 5
  selector:
    name: frontend
  template: { ... }
  triggers:
  - type: ConfigChange 1
  - imageChangeParams:
      automatic: true
      containerNames:
      - helloworld
      from:
        kind: ImageStreamTag
        name: hello-openshift:latest
    type: ImageChange  2
  strategy:
    type: Rolling      3

1
A configuration change trigger results in a new replication controller whenever changes are detected in the pod template of the deployment configuration.
2
An image change trigger causes a new deployment to be created each time a new version of the backing image is available in the named image stream.
3
The default Rolling strategy makes a downtime-free transition between deployments.

8.1.4. Comparing Deployment and DeploymentConfig objects

Both Kubernetes Deployment objects and OpenShift Container Platform-provided DeploymentConfig objects are supported in OpenShift Container Platform; however, it is recommended to use Deployment objects unless you need a specific feature or behavior provided by DeploymentConfig objects.

The following sections go into more detail on the differences between the two object types to further help you decide which type to use.

8.1.4.1. Design

One important difference between Deployment and DeploymentConfig objects is the properties of the CAP theorem that each design has chosen for the rollout process. DeploymentConfig objects prefer consistency, whereas Deployments objects take availability over consistency.

For DeploymentConfig objects, if a node running a deployer pod goes down, it will not get replaced. The process waits until the node comes back online or is manually deleted. Manually deleting the node also deletes the corresponding pod. This means that you can not delete the pod to unstick the rollout, as the kubelet is responsible for deleting the associated pod.

However, deployment rollouts are driven from a controller manager. The controller manager runs in high availability mode on masters and uses leader election algorithms to value availability over consistency. During a failure it is possible for other masters to act on the same deployment at the same time, but this issue will be reconciled shortly after the failure occurs.

8.1.4.2. Deployment-specific features
Rollover

The deployment process for Deployment objects is driven by a controller loop, in contrast to DeploymentConfig objects that use deployer pods for every new rollout. This means that the Deployment object can have as many active replica sets as possible, and eventually the deployment controller will scale down all old replica sets and scale up the newest one.

DeploymentConfig objects can have at most one deployer pod running, otherwise multiple deployers might conflict when trying to scale up what they think should be the newest replication controller. Because of this, only two replication controllers can be active at any point in time. Ultimately, this results in faster rapid rollouts for Deployment objects.

Proportional scaling

Because the deployment controller is the sole source of truth for the sizes of new and old replica sets owned by a Deployment object, it can scale ongoing rollouts. Additional replicas are distributed proportionally based on the size of each replica set.

DeploymentConfig objects cannot be scaled when a rollout is ongoing because the controller will have issues with the deployer process about the size of the new replication controller.

Pausing mid-rollout

Deployments can be paused at any point in time, meaning you can also pause ongoing rollouts. However, you currently cannot pause deployer pods; if you try to pause a deployment in the middle of a rollout, the deployer process is not affected and continues until it finishes.

8.1.4.3. DeploymentConfig object-specific features
Automatic rollbacks

Currently, deployments do not support automatically rolling back to the last successfully deployed replica set in case of a failure.

Triggers

Deployments have an implicit config change trigger in that every change in the pod template of a deployment automatically triggers a new rollout. If you do not want new rollouts on pod template changes, pause the deployment:

$ oc rollout pause deployments/<name>
Lifecycle hooks

Deployments do not yet support any lifecycle hooks.

Custom strategies

Deployments do not support user-specified custom deployment strategies.

8.2. Managing deployment processes

8.2.1. Managing DeploymentConfig objects

DeploymentConfig objects can be managed from the OpenShift Container Platform web console’s Workloads page or using the oc CLI. The following procedures show CLI usage unless otherwise stated.

8.2.1.1. Starting a deployment

You can start a rollout to begin the deployment process of your application.

Procedure

  1. To start a new deployment process from an existing DeploymentConfig object, run the following command:

    $ oc rollout latest dc/<name>
    Note

    If a deployment process is already in progress, the command displays a message and a new replication controller will not be deployed.

8.2.1.2. Viewing a deployment

You can view a deployment to get basic information about all the available revisions of your application.

Procedure

  1. To show details about all recently created replication controllers for the provided DeploymentConfig object, including any currently running deployment process, run the following command:

    $ oc rollout history dc/<name>
  2. To view details specific to a revision, add the --revision flag:

    $ oc rollout history dc/<name> --revision=1
  3. For more detailed information about a DeploymentConfig object and its latest revision, use the oc describe command:

    $ oc describe dc <name>
8.2.1.3. Retrying a deployment

If the current revision of your DeploymentConfig object failed to deploy, you can restart the deployment process.

Procedure

  1. To restart a failed deployment process:

    $ oc rollout retry dc/<name>

    If the latest revision of it was deployed successfully, the command displays a message and the deployment process is not retried.

    Note

    Retrying a deployment restarts the deployment process and does not create a new deployment revision. The restarted replication controller has the same configuration it had when it failed.

8.2.1.4. Rolling back a deployment

Rollbacks revert an application back to a previous revision and can be performed using the REST API, the CLI, or the web console.

Procedure

  1. To rollback to the last successful deployed revision of your configuration:

    $ oc rollout undo dc/<name>

    The DeploymentConfig object’s template is reverted to match the deployment revision specified in the undo command, and a new replication controller is started. If no revision is specified with --to-revision, then the last successfully deployed revision is used.

  2. Image change triggers on the DeploymentConfig object are disabled as part of the rollback to prevent accidentally starting a new deployment process soon after the rollback is complete.

    To re-enable the image change triggers:

    $ oc set triggers dc/<name> --auto
Note

Deployment configs also support automatically rolling back to the last successful revision of the configuration in case the latest deployment process fails. In that case, the latest template that failed to deploy stays intact by the system and it is up to users to fix their configurations.

8.2.1.5. Executing commands inside a container

You can add a command to a container, which modifies the container’s startup behavior by overruling the image’s ENTRYPOINT. This is different from a lifecycle hook, which instead can be run once per deployment at a specified time.

Procedure

  1. Add the command parameters to the spec field of the DeploymentConfig object. You can also add an args field, which modifies the command (or the ENTRYPOINT if command does not exist).

    kind: DeploymentConfig
    apiVersion: apps.openshift.io/v1
    metadata:
      name: example-dc
    # ...
    spec:
      template:
    # ...
        spec:
         containers:
         - name: <container_name>
           image: 'image'
           command:
             - '<command>'
           args:
             - '<argument_1>'
             - '<argument_2>'
             - '<argument_3>'

    For example, to execute the java command with the -jar and /opt/app-root/springboots2idemo.jar arguments:

    kind: DeploymentConfig
    apiVersion: apps.openshift.io/v1
    metadata:
      name: example-dc
    # ...
    spec:
      template:
    # ...
        spec:
          containers:
            - name: example-spring-boot
              image: 'image'
              command:
                - java
              args:
                - '-jar'
                - /opt/app-root/springboots2idemo.jar
    # ...
8.2.1.6. Viewing deployment logs

Procedure

  1. To stream the logs of the latest revision for a given DeploymentConfig object:

    $ oc logs -f dc/<name>

    If the latest revision is running or failed, the command returns the logs of the process that is responsible for deploying your pods. If it is successful, it returns the logs from a pod of your application.

  2. You can also view logs from older failed deployment processes, if and only if these processes (old replication controllers and their deployer pods) exist and have not been pruned or deleted manually:

    $ oc logs --version=1 dc/<name>
8.2.1.7. Deployment triggers

A DeploymentConfig object can contain triggers, which drive the creation of new deployment processes in response to events inside the cluster.

Warning

If no triggers are defined on a DeploymentConfig object, a config change trigger is added by default. If triggers are defined as an empty field, deployments must be started manually.

Config change deployment triggers

The config change trigger results in a new replication controller whenever configuration changes are detected in the pod template of the DeploymentConfig object.

Note

If a config change trigger is defined on a DeploymentConfig object, the first replication controller is automatically created soon after the DeploymentConfig object itself is created and it is not paused.

Config change deployment trigger

kind: DeploymentConfig
apiVersion: apps.openshift.io/v1
metadata:
  name: example-dc
# ...
spec:
# ...
  triggers:
    - type: "ConfigChange"

Image change deployment triggers

The image change trigger results in a new replication controller whenever the content of an image stream tag changes (when a new version of the image is pushed).

Image change deployment trigger

kind: DeploymentConfig
apiVersion: apps.openshift.io/v