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 oc. A script is available to facilitate removing/installing/updating the image streams.
.NET Core image streams can be defined in the global openshift namespace, or locally in a project namespace. To update the openshift namespace definitions, you need sufficient permissions.
Obtaining the RHEL 7 image streams requires authentication against the registry.redhat.io server using subscription credentials. These credentials are configured by adding a pull secret to the OpenShift namespace.
2.1.1. Install using oc
- If no pull secret is present in the namespace, you must add one by following the instructions in Red Hat Container Registry Authentication.
Run the following commands to 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.When .NET Core image streams are already installed, you can include newer versions by running:
$ oc replace -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.json
If no image streams for .NET Core are present, you can install them using:
$ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.json
2.1.2. Install using script
The script can be used to install/remove/update .NET Core image streams.
2.1.3. Linux/macOS
- Download the script from https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.sh
-
Login to the OpenShift cluster using the
oc logincommand. Install/update the imagestreams.
./install-imagestreams.sh --os rhel7 [--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.
You can run ./install-imagestreams.sh --help for more information on using this script.
2.1.4. Windows
- Download the script from https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/install-imagestreams.ps1
-
Login to the OpenShift cluster using the
oc logincommand. Install/update the imagestreams.
./install-imagestreams.sh --OS rhel7 [--Namespace <namespace>] [-User <subscription_user> -Password <subscription_password>]
The PowerShell ExecutionPolicy may prohibit executing this script. To relax the policy, you can 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.
You can run Get-Help .\install-imagestreams.ps1 for more information on using this script.
2.2. Deploying Applications from Source
Run the following commands to deploy the ASP.NET Core application, which is in the
appfolder on thedotnetcore-3.1branch of theredhat-developer/s2i-dotnetcore-exGitHub 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
Use the
oc logscommand to track progress of the build.$ oc logs -f bc/exampleapp
View the deployed application once the build is finished.
$ oc logs -f dc/exampleapp
At this point, the application is accessible within the project. To make it accessible externally, use the
oc exposecommand. You can then useoc get routesto find the URL.$ oc expose svc/exampleapp $ oc get routes
2.3. Deploying Applications from Binary Artifacts
The .NET Core S2I builder image can be used to build an application using binary artifacts that you provide.
Publish your application as described in Publish 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
Create a new binary build using the
oc new-buildcommand.$ oc new-build --name=mywebapp dotnet:3.1 --binary=true
Start a build using the
oc start-buildcommand, specifying the path to the binary artifacts on your local machine.$ oc start-build mywebapp --from-dir=bin/Release/netcoreapp3.1/publish
Create a new application using the
oc new-appcommand.$ oc new-app mywebapp
2.4. Using a Jenkins Slave
The OpenShift Container Platform Jenkins image provides auto-discovery of the .NET Core 3.1 slave image (dotnet-31). For auto-discovery to work, you need to add a Jenkins slave ConfigMap yaml file to the project.
Change to the project where Jenkins is (or will be) deployed.
$ oc project <projectname>
Create a
dotnet-jenkins-slave.yamlfile. The value used for the <serviceAccount> element is the account used by the Jenkins slave. If no value is specified, thedefaultservice account is used.kind: ConfigMap apiVersion: v1 metadata: name: dotnet-jenkins-slave-31 labels: role: jenkins-slave data: dotnet31: |- <org.csanchez.jenkins.plugins.kubernetes.PodTemplate> <inheritFrom></inheritFrom> <name>dotnet-31</name> <instanceCap>2247483647</instanceCap> <idleMinutes>0</idleMinutes> <label>dotnet-31</label> <serviceAccount>jenkins</serviceAccount> <nodeSelector></nodeSelector> <volumes/> <containers> <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate> <name>jnlp</name> <image>registry.access.redhat.com/dotnet/dotnet-31-jenkins-slave-rhel7:latest</image> <privileged>false</privileged> <alwaysPullImage>true</alwaysPullImage> <workingDir>/tmp</workingDir> <command></command> <args>${computer.jnlpmac} ${computer.name}</args> <ttyEnabled>false</ttyEnabled> <resourceRequestCpu></resourceRequestCpu> <resourceRequestMemory></resourceRequestMemory> <resourceLimitCpu></resourceLimitCpu> <resourceLimitMemory></resourceLimitMemory> <envVars/> </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate> </containers> <envVars/> <annotations/> <imagePullSecrets/> <nodeProperties/> </org.csanchez.jenkins.plugins.kubernetes.PodTemplate>Import the configuration into the project.
$ oc create -f dotnet-jenkins-slave.yaml
The slave image can now be used.
Example: The following example shows a Jenkins pipeline added to OpenShift Container Platform. Note that when a Jenkins pipeline is added and no Jenkins master is running, OpenShift automatically deploys a master. See OpenShift Container Platform and Jenkins for additional information about deploying and configuring a Jenkins server instance.
In the example steps, the BuildConfig yaml file includes a simple Jenkins pipeline configured using the dotnet-31 Jenkins slave. There are three stages in the example BuildConfig yaml file:
-
First, the sources are checked out.
-
Second, the application is published.
- Third, the image is assembled using a binary build. See Deploying Applications from Binary Artifacts for additional information about binary builds.
Complete the steps below to configure the example Jenkins master-slave pipeline.
Create the
buildconfig.yamlfile.kind: BuildConfig apiVersion: v1 metadata: name: dotnetapp-build spec: strategy: type: JenkinsPipeline jenkinsPipelineStrategy: jenkinsfile: |- node("dotnet-31") { stage('clone sources') { sh "git clone https://github.com/redhat-developer/s2i-dotnetcore-ex --branch dotnetcore-3.1 ." } stage('publish') { dir('app') { sh "dotnet publish -c Release" } } stage('create image') { dir('app') { sh 'oc new-build --name=dotnetapp dotnet:3.1 --binary=true || true' sh 'oc start-build dotnetapp --from-dir=bin/Release/netcoreapp3.1/publish --follow' } } }Import the
BuildConfigfile to OpenShift.$ oc create -f buildconfig.yaml
-
Launch the OpenShift console. Go to Builds > Pipelines. The
dotnetapp-buildpipeline is available. Click Start Pipeline. It may take a while for the build to start because the Jenkins image(s) need to be downloaded first.
During the build you can watch the different pipeline stages complete in the OpenShift console. You can also click View Log to see the pipeline stages complete in Jenkins.
-
When the Jenkins pipeline build completes, go to Builds > Images. The
dotnetappimage is built and available.
2.5. 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 an .s2i/environment file in the application source code repository.
| Variable Name | Description | Default |
|---|---|---|
| DOTNET_STARTUP_PROJECT |
Selects project to run. This must be a project file (for example, |
|
| DOTNET_ASSEMBLY_NAME |
Selects the assembly to run. This must not include the .dll extension. Set this to the output assembly name specified in |
The name of the |
| DOTNET_PUBLISH_READRYTORUN |
When set to |
|
| 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 | |
| DOTNET_RESTORE_CONFIGFILE |
Specifies a | |
| 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 | |
| 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_CONFIGURATION |
Runs the application in Debug or Release mode. This value should be either |
|
| DOTNET_VERBOSITY |
Specifies the verbosity of the | |
| HTTP_PROXY, HTTPS_PROXY | Configures the HTTP/HTTPS proxy used when building and running the application. | |
| DOTNET_RM_SRC |
When set to | |
| DOTNET_SSL_DIRS |
Used to specify a list of folders/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 | |
| NPM_MIRROR | Uses a custom NPM registry mirror to download packages during the build process. | |
| ASPNETCORE_URLS |
This variable is set to | |
| 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. |
|
| DOTNET_INCREMENTAL | When set to true, the NuGet packages will be kept so they can be re-used for an incremental build. |
|
| DOTNET_PACK |
When set to true, creates a |
2.6. Sample Applications
Two sample applications are available for use with the .NET Core s2i builder.
2.6.1. s2i-dotnetcore-ex
s2i-dotnetcore-ex is the default .NET Core 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 oc as follows:
# 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 # Make the .NET Core application accessible externally and show the url $ oc expose service s2i-dotnetcore-ex $ oc get route s2i-dotnetcore-ex
For more information about this application, see https://github.com/redhat-developer/s2i-dotnetcore-ex/tree/dotnetcore-3.1.
2.6.2. s2i-dotnetcore-persistent-ex
s2i-dotnetcore-persistent-ex is the a simple CRUD .NET Core web application that stores data in a PostgreSQL database.
The application can be created using the OpenShift client oc as follows:
# Add the database $ oc new-app postgresql-ephemeral # 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 # Add envvars from the the postgresql secret, and database service name envvar. $ oc set env dc/s2i-dotnetcore-persistent-ex --from=secret/postgresql -e database-service=postgresql # Make the .NET Core application accessible externally and show the url $ oc expose service s2i-dotnetcore-persistent-ex $ oc get route s2i-dotnetcore-persistent-ex
For more information about this application, see https://github.com/redhat-developer/s2i-dotnetcore-persistent-ex/tree/dotnetcore-3.1.