Building applications

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

   
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.

Procedure

1. In the Administrator perspective, navigate to Administration → Cluster 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.

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.

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 Administration → Cluster 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.

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.

Procedure

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

   • Using the web console:

     1. Navigate to the Administration → Cluster 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.

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.

Procedure

1. In the +Add view, click the Getting Started resources → Build with guided documentation → View 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.

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 Preferences → Applications → Resource 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 Settings → Webhooks 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.

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 options → Resource 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.

Procedure

1. Navigate to Developer Perspective → +Add → Developer Catalog → All 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.

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

   

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>

Procedure

1. In the Administrator perspective of the web console, navigate to Operators → OperatorHub.
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.

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.

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

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.

Procedure

1. To deploy the Dev4Devs PostgreSQL Operator in the my-petclinic namespace run the following command in shell:

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

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

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.

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

   

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.

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

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

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

   
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

   

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

   
5. Optional: If there is difficulty in making a binding connection using the Topology view, go to +Add → YAML → Import 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

   
   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

   
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.

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.

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"}

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.

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.

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"}

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

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

   

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.

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

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

   
   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.

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

   

   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.

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

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 ( ) icon.

Procedure

1. In the Topology view, select the Helm release to see the side panel.
2. Click Actions → Upgrade 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.

1. In the Developer perspective, navigate to the Helm view to see the Helm Releases in the namespace.
2. Click the Options menu 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

   
6. If required, you can further use the Options menu adjoining a particular revision and select the revision to rollback to.

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.

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.