Chapter 3. Creating applications

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 Red Hat OpenShift Service on AWS 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 +Add view, click Container images to view the Deploy Images page.

2. In the Image section:

   1. Select Image name from external registry to deploy an image from a public or a private registry, or select Image stream tag from internal registry to deploy an image from an internal registry.
   2. Select an icon for your image in the Runtime icon tab.

3. In the General section:

   1. In the Application name field, enter a unique name for the application grouping.
   2. In the Name field, enter a unique name to identify the resources created for this component.

4. In the Resource type section, select the resource type to generate:

   1. Select Deployment to enable declarative updates for Pod and ReplicaSet objects.
   2. Select DeploymentConfig to define the template for a Pod object, and manage deploying new images and configuration sources.
   3. Select Serverless Deployment to enable scaling to zero when idle.
5. Click Create. You can view 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: Use the Resource type drop-down list to change the resource type.
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 Red Hat OpenShift Service on AWS web console for this procedure. This example uses a project called my-etcd.

2. Navigate to the Ecosystem Installed Operators page.

   The Operators installed on the cluster by the dedicated-admin and available for use are shown here as a list of cluster service versions (CSVs). Each CSV launches and manages the software provided by the Operator.

   Tip

   You can get this list from the CLI by running the following command:

   $ 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 similarly 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. Optional: Modify the minimal starting template of an EtcdCluster object, such as the size of the cluster.
   3. 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.

6. Click the Resources tab.

   Your project contains several resources that the Operator created and configured.

7. Verify that a Kubernetes service exists that allows you to access the database from other pods in your project.

8. Optional: To grant another user permission to create Operator-managed applications in the project, add the edit role by running the following command:

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

   Users with the edit role in a project can create, manage, and delete Operator-managed application instances, such as an etcd cluster.

Procedure

1. Create an application from a Git repository in a local directory by running the following command:

   $ 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 Red Hat OpenShift Service on AWS cluster. If there is no recognized remote, running the new-app command creates a binary build.

2. Create an application from a public remote Git repository by running the following command:

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

3. Create an application from a private remote Git repository by running the following command:

   $ oc new-app https://github.com/<your_user>/<your_private_repo> --source-secret=yoursecret

   Note

   If you use a private remote Git repository, use the --source-secret flag to specify a source clone secret for access to the repository.

4. Use a subdirectory of your source repository by running the following command:

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

5. Specify a Git branch by running the following command:

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

6. Override the automatically detected build strategy by running the following command:

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

7. Specify the builder image and source repository:

   1. Specify the builder image and source repository for a remote repository by running the following command:

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

   2. Specify the builder image and source repository for a local repository by running the following command:

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

Procedure

1. Upload an application template to the template library of your current project by running the following command:

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

2. Create a new application from a stored template by running the following command:

   $ oc new-app ruby-helloworld-sample

3. Create a new application from a template file on your local file system without storing it in Red Hat OpenShift Service on AWS by running the following command:

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

4. Set template parameter values when creating an application by running the following command:

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

5. Store template parameters in a file by creating a file such as helloworld.params with the following content:

   ADMIN_USERNAME=admin
   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=-.

6. Create a new application from a template by using a parameter file by running the following command:

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

   Note

   To read parameters from standard input, use --param-file=-.