Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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

2.1. Installing Image Streams
Copy link

The .NET Core image streams definition can be defined globally in the openshift namespace or locally in your specific project.

  1. If you are a system administrator or otherwise have sufficient permissions, change to the openshift project. Using the openshift project allows you to globally update the image stream definitions. 

    $ oc project openshift

    If you do not have permissions to use the openshift project, you can still update your project definitions starting with Step 2.

  2. Run the following commands to 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.

  3. To pull the images, OpenShift needs credentials for authenticating with the registry.redhat.io server. These credentials are stored in a secret.

    Note

    For OpenShift 3.11 and later, a secret is preconfigured for the openshift namespace.

  4. Enter the following command to list secrets. The first column shows the secret name. 

    $ oc get secret | grep kubernetes.io/dockerc

  5. To check the contents of a secret, you can decode the .dockercfg or .dockerconfigjson data from Base64 format. This allows you to see if you already have credentials for the registry.redhat.io server. Enter the following command to show the .dockercfg section in a secret. 

    $ oc get secret <secret-name> -o yaml | grep .dockercfg
  .dockercfg: eyJyZWdpc3RyeS5yZWRoYXQuaW8iOnsidXNlcm5hbWUiOiIqKioqKioqKiIsInBhc3N3b3JkIjoiKioqKioqKioiLCJlbWFpbCI6InVudXNlZCIsImF1dGgiOiJLaW9xS2lvcUtpbzZLaW9xS2lvcUtpbz0ifX0=

  6. 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.io server. 

    $ echo eyJyZWdpc3RyeS5yZWRoYXQuaW8iOnsidXNlcm5hbWUiOiIqKioqKioqKiIsInBhc3N3b3JkIjoiKioqKioqKioiLCJlbWFpbCI6InVudXNlZCIsImF1dGgiOiJLaW9xS2lvcUtpbzZLaW9xS2lvcUtpbz0ifX0= | base64 -d
{"registry.redhat.io":{"username":"********","password":"********","email":"unused","auth":"KioqKioqKio6KioqKioqKio="}}

    You need to add a secret if there is no secret listed with credentials for the registry.redhat.io server.

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

  8. After creating the secret, enter the following command to import 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 replace command to update the image stream definitions. 

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

2.2. Deploying Applications from Source
Copy link

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

    $ oc new-app --name=exampleapp 'dotnet:3.0~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-3.0' --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. At this point, the application is accessible within the project. To make it 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.3. Deploying Applications from Binary Artifacts
Copy link

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

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

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

    $ oc new-build --name=mywebapp dotnet:3.0 --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.0/publish

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

    $ oc new-app mywebapp

2.4. Using a Jenkins Slave
Copy link

The OpenShift Container Platform Jenkins image provides auto-discovery of the .NET Core 3.0 slave image (dotnet-30). For auto-discovery to work, you need to add a Jenkins slave ConfigMap yaml file to the project.

  1. Change to the project where Jenkins is (or will be) deployed. 

    $ oc project <projectname>

  2. Create a dotnet-jenkins-slave.yaml file. The value used for the <serviceAccount> element is the account used by the Jenkins slave. If no value is specified, the default service account is used. 

    kind: ConfigMap
apiVersion: v1
metadata:
  name: dotnet-jenkins-slave-30
  labels:
    role: jenkins-slave
data:
  dotnet30: |-
    <org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
      <inheritFrom></inheritFrom>
      <name>dotnet-30</name>
      <instanceCap>2247483647</instanceCap>
      <idleMinutes>0</idleMinutes>
      <label>dotnet-30</label>
      <serviceAccount>jenkins</serviceAccount>
      <nodeSelector></nodeSelector>
      <volumes/>
      <containers>
        <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
          <name>jnlp</name>
          <image>registry.access.redhat.com/dotnet/dotnet-30-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>

  3. 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-30 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.

  1. Create the buildconfig.yaml file. 

    kind: BuildConfig
apiVersion: v1
metadata:
  name: dotnetapp-build
spec:
  strategy:
    type: JenkinsPipeline
    jenkinsPipelineStrategy:
      jenkinsfile: |-
        node("dotnet-30") {
          stage('clone sources') {
            sh "git clone https://github.com/redhat-developer/s2i-dotnetcore-ex --branch dotnetcore-3.0 ."
          }
          stage('publish') {
            dir('app') {
              sh "dotnet publish -c Release"
            }
          }
          stage('create image') {
            dir('app') {
              sh 'oc new-build --name=dotnetapp dotnet:3.0 --binary=true || true'
              sh 'oc start-build dotnetapp --from-dir=bin/Release/netcoreapp3.0/publish --follow'
            }
          }
        }

  2. Import the BuildConfig file to OpenShift. 

    $ oc create -f buildconfig.yaml
  3. Launch the OpenShift console. Go to Builds > Pipelines. The dotnetapp-build pipeline is available.

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

  5. When the Jenkins pipeline build completes, go to Builds > Images. The dotnetapp image is built and available.

2.5. Environment Variables
Copy link

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.

Expand
Variable NameDescriptionDefault

DOTNET_STARTUP_PROJECT

Selects 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/HTTPS proxy used when building and running the application.

 

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/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.6. Sample Applications
Copy link

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-30-rhel7. The result is deployed in dotnet/dotnet-30-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.

    Note

    This application uses .NET Core 2.1 LTS.

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

Report a bug

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top