Chapter 3. Using .NET Core 2.1 on OpenShift Container Platform
You can install .NET Core image streams on Linux, Mac, or Windows operating system.
3.1. Installing .NET Core 2.1 image streams
.NET Core image streams definition can be defined globally in the openshift namespace or locally in your specific project.
Procedure
If you are a system administrator or otherwise have sufficient permissions, change to the
openshiftproject. Using theopenshiftproject allows you to globally update the image stream definitions.$ oc project openshift
If you do not have permissions to use the
openshiftproject, you can still update your project definitions starting with Step 2.List all available .NET Core image versions:
$ oc describe is dotnet -n openshift $ oc describe is dotnet
The output shows installed images or the message
Error from server (NotFound)if no images are installed.To pull the images, OpenShift needs credentials for authenticating with the
registry.redhat.io server. These credentials are stored in a secret.NoteFor OpenShift 3.11 and later, a secret is preconfigured for the
openshiftnamespace.Enter the following command to list secrets. The first column shows the secret name.
$ oc get secret | grep kubernetes.io/dockerc
To check the contents of a secret, you can decode the
.dockercfgor.dockerconfigjsondata from Base64 format. This allows you to see if you already have credentials for theregistry.redhat.io server. Enter the following command to show the.dockercfgsection in a secret.$ oc get secret <secret-name> -o yaml | grep .dockercfg .dockercfg: eyJyZWdpc3RyeS5yZWRoYXQuaW8iOnsidXNlcm5hbWUiOiIqKioqKioqKiIsInBhc3N3b3JkIjoiKioqKioqKioiLCJlbWFpbCI6InVudXNlZCIsImF1dGgiOiJLaW9xS2lvcUtpbzZLaW9xS2lvcUtpbz0ifX0=
Copy and paste the output in the following command to convert it from Base64 format. The example below shows the credentials for the
registry.redhat.ioserver.$ echo eyJyZWdpc3RyeS5yZWRoYXQuaW8iOnsidXNlcm5hbWUiOiIqKioqKioqKiIsInBhc3N3b3JkIjoiKioqKioqKioiLCJlbWFpbCI6InVudXNlZCIsImF1dGgiOiJLaW9xS2lvcUtpbzZLaW9xS2lvcUtpbz0ifX0= | base64 -d {"registry.redhat.io":{"username":"","password":"","email":"unused","auth":"KioqKioqKio6KioqKioqKio="}}If there is no secret listed with credentials for the
registry.redhat.ioserver you need to add it.Red Hat account credentials are used for
registry.redhat.io access. If you are a customer with entitlements to Red Hat products, you already have account credentials to use. These are typically the same credentials used to log in to the Red Hat Customer Portal. To verify your Red Hat credentials, enter the following command and attempt to log in.$ podman login registry.redhat.io
If you cannot log in, you first need to get an account with Red Hat. See Red Hat Container Registry Authentication for additional information. If you can log in, enter the following commands to create the secret.
$ oc create secret docker-registry redhat-registry \ --docker-server=registry.redhat.io \ --docker-username=<user-name> \ --docker-password=<password> \ --docker-email=unused $ oc secrets link default redhat-registry --for=pull $ oc secrets link builder redhat-registryImport new image streams:
$ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.json
If image streams were already installed, use the
replacecommand to update the image stream definitions.$ oc replace -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.json
3.2. Deploying applications from source using oc
You can use OpenShift Client (oc) for application deployment.
The following example demonstrates how to deploy the example-app application using oc, which is in the app folder on the dotnetcore-2.1 branch of the redhat-developer/s2i-dotnetcore-ex GitHub repository:
Procedure
Create a new OpenShift project:
$ oc new-project sample-projectAdd the ASP.NET Core application:
$ oc new-app --name=example-app 'dotnet:2.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-2.1' --build-env DOTNET_STARTUP_PROJECT=appTrack the progress of the build:
$ oc logs -f bc/example-appView the deployed application once the build is finished:
$ oc logs -f dc/example-appThe application is now accessible within the project.
Optional: Make the project accessible externally:
$ oc expose svc/example-appObtain the shareable URL:
$ oc get routes
3.3. Deploying applications from binary artifacts using oc
You can use .NET Core Source-to-Image (S2I) builder image to build applications using binary artifacts that you provide.
Prerequisites
Published application.
For more information, see Section 2.3, “Publishing applications using .NET Core 2.1”.
Procedure
Create a new binary build:
$ oc new-build --name=my-web-app dotnet:2.1 --binary=trueStart the build and specify the path to the binary artifacts on your local machine:
$ oc start-build my-web-app --from-dir=bin/Release/netcoreapp2.1/publish
Create a new application:
$ oc new-app my-web-app
3.4. Using Jenkins slave
The OpenShift Container Platform Jenkins image provides auto-discovery of the .NET Core 2.1 slave image (dotnet-21).
For auto-discovery to work, you need to add a Jenkins slave ConfigMap yaml file to the project.
Procedure
Change to the project where Jenkins is (or will be) deployed:
$ oc project _project-name_
Create a
dotnet-jenkins-slave.yamlfile:NoteThe value used for the <serviceAccount> element is the account used by the Jenkins slave. If no value is specified, the
defaultservice account is used.kind: ConfigMap apiVersion: v1 metadata: name: dotnet-jenkins-slave-21 labels: role: jenkins-slave data: dotnet21: |- <org.csanchez.jenkins.plugins.kubernetes.PodTemplate> <inheritFrom></inheritFrom> <name>dotnet-21</name> <instanceCap>2147483647</instanceCap> <idleMinutes>0</idleMinutes> <label>dotnet-21</label> <serviceAccount>jenkins</serviceAccount> <nodeSelector></nodeSelector> <volumes/> <containers> <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate> <name>jnlp</name> <image>registry.access.redhat.com/dotnet/dotnet-21-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-21 Jenkins slave. There are three stages in the example BuildConfig yaml file:
- The sources are checked out.
- The application is published.
The image is assembled using a binary build.
See Section 3.3, “Deploying applications from binary artifacts using
oc” for additional information about binary builds.
Procedure
To configure the Jenkins master-slave pipeline:
Create the
buildconfig.yamlfile:kind: BuildConfig apiVersion: v1 metadata: name: dotnetapp-build spec: strategy: type: JenkinsPipeline jenkinsPipelineStrategy: jenkinsfile: |- node("dotnet-21") { stage('clone sources') { sh "git clone https://github.com/redhat-developer/s2i-dotnetcore-ex --branch dotnetcore-2.1 ." } stage('publish') { dir('app') { sh "dotnet publish -c Release /p:MicrosoftNETPlatformLibrary=Microsoft.NETCore.App" } } stage('create image') { dir('app') { sh 'oc new-build --name=dotnetapp dotnet:2.1 --binary=true || true' sh 'oc start-build dotnetapp --from-dir=bin/Release/netcoreapp2.1/publish --follow' } } }Import the
BuildConfigfile to OpenShift:$ oc create -f buildconfig.yaml
- Open the OpenShift console.
Go to Builds → Pipelines.
The
dotnetapp-buildpipeline is available.Click Start Pipeline.
Mote that 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 is complete, go to Builds → Images.
The
dotnetappimage is built and available.
3.5. Environmental variables for .NET Core 2.1
The .NET Core images support several environment variables to control the build behavior of your .NET Core application. You can set these variables as part of the build configuration, or add them to the .s2i/environment file in the application source code repository.
| Variable Name | Description | Default |
|---|---|---|
| DOTNET_STARTUP_PROJECT |
Selects the project to run. This must be a project file (for example, |
|
| DOTNET_ASSEMBLY_NAME |
Selects the assembly to run. This must not include the |
The name of the |
| 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_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 or HTTPS proxy used when building and running the application, respectively. | |
| DOTNET_RM_SRC |
When set to | |
| DOTNET_SSL_DIRS |
Specifies 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 | |
| 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 |
|
| DOTNET_INCREMENTAL |
When set to | |
| DOTNET_PACK |
When set to | |
| [OBSOLETE: April 2019] - DOTNET_SDK_VERSION |
Selects the default sdk version when building. If there is a | Lowest sdk version available in the image |
3.6. Creating sample applications for .NET Core 2.1
Three sample applications are available:
- dotnet-example: This is the default model–view–controller (MVC) application.
-
dotnet-runtime-example: This shows how to build an MVC application using a chained build. The application is built in
dotnet/dotnet-21-rhel7. The result is deployed inubi8/dotnet-21-runtime-rhel7. Note that chained builds are not supported on OpenShift Online. - dotnet-pgsql-persistent: This is the Microsoft ASP.NET Core MusicStore sample application using a PostgreSQL backend.
To add the samples using the OpenShift Web Console, browse to your project and click Add to project. You can filter for dotnet. If the samples do not show up, you can add them to your installation by running the following commands:
$ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/templates/dotnet-example.json $ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/templates/dotnet-runtime-example.json $ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/templates/dotnet-pgsql-persistent.json