Chapter 2. Using .NET Core 3.1 on Red Hat OpenShift Container Platform

2.1. Installing image streams

.NET Core image streams are installed using image stream definitions from s2i-dotnetcore with the OpenShift client binary (oc). A script is available to facilitate removing, installing, and updating the image streams.

.NET Core image streams can be defined in the global openshift namespace or locally in a project namespace. Sufficient permissions are required to update the openshift namespace definitions.

2.1.1. Installing image streams using oc

Prerequisites

Procedure

  1. List the available .NET Core image streams: 

    $ oc describe is dotnet [-n <namespace>]

    The output shows installed images or the message Error from server (NotFound) if no images are installed.

  2. Install the .NET Core image streams: 

    $ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams_rhel8.json

  3. Include newer versions of existing .NET Core image streams: 

    $ oc replace -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams_rhel8.json

2.1.2. Installing image streams using a script

The script can be used to install, remove, and update .NET Core image streams.

2.1.2.1. Linux/macOS

Procedure

  1. Download the script.
  2. Log in to the OpenShift cluster using the oc login command.

  3. Install or update the image streams: 

    ./install-imagestreams.sh --os rhel8 [--namespace <namespace>]  [--user <subscription_user> --password <subscription_password>]

The pull secret can be added by providing the --user and --password arguments. If a pull secret is already present, these arguments are ignored.

Run ./install-imagestreams.sh --help for more information on using this script.

2.1.2.2. Windows

Procedure

  1. Download the script.
  2. Log in to the OpenShift cluster using the oc login command.

  3. Install or update the image streams: 

    ./install-imagestreams.sh --OS rhel8 [--Namespace <namespace>]  [-User <subscription_user> -Password <subscription_password>]
Note

The PowerShell ExecutionPolicy may prohibit executing this script. To relax the policy, run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force.

The pull secret can be added by providing the -User and -Password arguments. If a pull secret is already present, these arguments are ignored.

Run Get-Help .\install-imagestreams.ps1 for more information on using this script.

2.2. Deploying applications

2.2.1. Deploying applications from source

Procedure

  1. Run the following commands to deploy the ASP.NET Core application, which is in the app folder on the dotnetcore-3.1 branch of the redhat-developer/s2i-dotnetcore-ex GitHub repository: 

    $ oc new-app --name=exampleapp 'dotnet:3.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-3.1' --build-env DOTNET_STARTUP_PROJECT=app

  2. Use the oc logs command to track progress of the build: 

    $ oc logs -f bc/exampleapp

  3. View the deployed application once the build is finished: 

    $ oc logs -f dc/exampleapp

  4. The application is now accessible within the project. To make the project accessible externally, use the oc expose command. You can then use oc get routes to find the URL: 

    $ oc expose svc/exampleapp
$ oc get routes

2.2.2. Deploying applications from binary artifacts

The .NET Core Source-to-Image (S2I) builder image can be used to build an application using binary artifacts that you provide.

Procedure

  1. Publish your application as described in Section 1.3, “Publishing applications”. For example, the following commands create a new web application and publish it: 

    $ dotnet new web -o webapp
$ cd webapp
$ dotnet publish -c Release

  2. Create a new binary build using the oc new-build command: 

    $ oc new-build --name=mywebapp dotnet:3.1 --binary=true

  3. Start a build using the oc start-build command, specifying the path to the binary artifacts on your local machine: 

    $ oc start-build mywebapp --from-dir=bin/Release/netcoreapp3.1/publish

  4. Create a new application using the oc new-app command: 

    $ oc new-app mywebapp

2.3. Environment variables

The .NET Core images support a number of environment variables to control the build behavior of your .NET Core application. These variables can be set as part of the build configuration, or they can be added to the .s2i/environment file in the application source code repository.

Variable NameDescriptionDefault

DOTNET_STARTUP_PROJECT

Selects the project to run. This must be a project file (for example, csproj or fsproj) or a folder containing a single project file.

.

DOTNET_ASSEMBLY_NAME

Selects the assembly to run. This must not include the .dll extension. Set this to the output assembly name specified in csproj (PropertyGroup/AssemblyName).

The name of the csproj file

DOTNET_PUBLISH_READRYTORUN

When set to true, the application will be compiled ahead-of-time. This reduces startup time by reducing the amount of work the JIT needs to do when the application is loading.

false

DOTNET_RESTORE_SOURCES

Specifies the space-separated list of NuGet package sources used during the restore operation. This overrides all of the sources specified in the NuGet.config file. This variable cannot be combined with DOTNET_RESTORE_CONFIGFILE.

 

DOTNET_RESTORE_CONFIGFILE

Specifies a NuGet.Config file to be used for restore operations. This variable cannot be combined with DOTNET_RESTORE_SOURCES.

 

DOTNET_TOOLS

Specifies a list of .NET tools to install before building the app. It is possible to install a specific version by post pending the package name with @<version>.

 

DOTNET_NPM_TOOLS

Specifies a list of NPM packages to install before building the application.

 

DOTNET_TEST_PROJECTS

Specifies the list of test projects to test. This must be project files or folders containing a single project file. dotnet test is invoked for each item.

 

DOTNET_CONFIGURATION

Runs the application in Debug or Release mode. This value should be either Release or Debug.

Release

DOTNET_VERBOSITY

Specifies the verbosity of the dotnet build commands. When set, the environment variables are printed at the start of the build. This variable can be set to one of the msbuild verbosity values (q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]).

 

HTTP_PROXY, HTTPS_PROXY

Configures the HTTP or HTTPS proxy used when building and running the application, respectively.

 

DOTNET_RM_SRC

When set to true, the source code will not be included in the image.

 

DOTNET_SSL_DIRS

Used to specify a list of folders or files with additional SSL certificates to trust. The certificates are trusted by each process that runs during the build and all processes that run in the image after the build (including the application that was built). The items can be absolute paths (starting with /) or paths in the source repository (for example, certificates).

 

NPM_MIRROR

Uses a custom NPM registry mirror to download packages during the build process.

 

ASPNETCORE_URLS

This variable is set to http://*:8080 to configure ASP.NET Core to use the port exposed by the image. Changing this is not recommended.

http://*:8080

DOTNET_RESTORE_DISABLE_PARALLEL

When set to true, disables restoring multiple projects in parallel. This reduces restore timeout errors when the build container is running with low CPU limits.

false

DOTNET_INCREMENTAL

When set to true, the NuGet packages will be kept so they can be re-used for an incremental build.

false

DOTNET_PACK

When set to true, creates a tar.gz file at /opt/app-root/app.tar.gz that contains the published application.

 

2.4. Sample applications

Two sample applications are available for use with the .NET Core S2I builder.

2.4.1. Creating the MVC sample application

s2i-dotnetcore-ex is the default .NET Core Model, View, Controller (MVC) template application.

This application is used as the example application by the .NET Core S2I image and can be created directly from the OpenShift UI using the Try Example link.

The application can also be created with the OpenShift client binary (oc).

Procedure

To create the sample application using oc:

  1. Add the .NET Core application: 

    $ oc new-app dotnet:3.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-3.1 --context-dir=app

  2. Make the .NET Core application externally accessible and show the URL: 

    $ oc expose service s2i-dotnetcore-ex
$ oc get route s2i-dotnetcore-ex

Additional resources

2.4.2. Creating the CRUD sample application

s2i-dotnetcore-persistent-ex is a simple Create, Read, Update, Delete (CRUD) .NET Core web application that stores data in a PostgreSQL database.

Procedure

The application can be created using the OpenShift client oc as follows:

  1. Add the database: 

    $ oc new-app postgresql-ephemeral

  2. Add the .NET Core application: 

    $ oc new-app dotnet:3.1~https://github.com/redhat-developer/s2i-dotnetcore-persistent-ex#dotnetcore-3.1 --context-dir app

  3. Add environment variables from the postgresql secret and database service name environment variable: 

    $ oc set env dc/s2i-dotnetcore-persistent-ex --from=secret/postgresql -e database-service=postgresql

  4. Make the .NET Core application externally accessible and show the URL: 

    $ oc expose service s2i-dotnetcore-persistent-ex
$ oc get route s2i-dotnetcore-persistent-ex

Additional resources