Chapter 2. .NET Core 2.0 on Red Hat OpenShift Container Platform

2.1. Install Image Streams

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 command to list all available .NET Core image versions.

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

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

    $ oc get secret | grep kubernetes.io/dockercfg

    To check the contents of a secret, you can decode the .dockercfg or .dockercfgjson 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=

    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.

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

    $ docker 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
  5. 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. Deploy Applications

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

    $ oc new-app --name=exampleapp 'dotnet:2.0~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-2.0' --build-env DOTNET_STARTUP_PROJECT=app
  2. As suggested by the output of the new-app command, you can track progress of the build using the oc logs command.

    $ oc logs -f bc/exampleapp
  3. Once the build is finished, you can see the deployed application.

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

DOTNET_STARTUP_PROJECT

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

.

DOTNET_SDK_VERSION

Used to select the default sdk version when building. If there is a global.json file in the source repository, that takes precedence. When set to latest the latest sdk in the image is used.

Lowest sdk version available in the image

DOTNET_ASSEMBLY_NAME

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

Name of the csproj file

DOTNET_RESTORE_SOURCES

Used to specify 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.

 

DOTNET_NPM_TOOLS

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

 

DOTNET_TEST_PROJECTS

Used to specify 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_VERBOSITY

Used to specify 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]).

 

DOTNET_CONFIGURATION

Used to run the application in Debug or Release mode. This value should be either Release or Debug.

Release

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

HTTP_PROXY, HTTPS_PROXY

Configures the HTTP/HTTPS proxy used when building and running the application.

 

NPM_MIRROR

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

 

DOTNET_ASPNET_STORE

Publish assuming the runtime image contains the ASP.NET Core runtime store.

false

2.4. Sample Applications

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 and the .NET runtime image.
  • 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

2.5. Create a Runtime Image

The .NET Core runtime image contains the files sufficient to run a .NET application, but not to build one. As such, you must provide an already published application for the runtime image. This can be a static application inside of an image that layers on top of the runtime image or a new image can be built that is fed the application from a build image. This last method is commonly referred to as chaining builds.

Deploying a build chain requires a more in-depth configuration than a simple application build. At a minimum, a build chain needs:

  • a build config for the build image
  • a build config for the runtime image
  • an inline dockerfile for the runtime image
  • a deployment config that uses the runtime image

The following elements are optional but recommended:

  • an internal image stream
  • a trigger for the build image based on the source project
  • a trigger for the runtime build based on the build image

See dotnet-runtime-example template for an example of such a configuration.

In this template, we define a *-build and a *-runtime build config. The build image builds from a GitHub project and has a trigger to rebuild automatically when the project changes or when the base image (in this case, dotnet-20-rhel7) updates.

The runtime image builds from the dotnet-20-runtime-rhel7 base image but pulls a tar.gz file from the build image that contains the build project. That is done using this source definition in the build config.

"source": {
    "dockerfile": "FROM ${DOTNET_RUNTIME_IMAGE_STREAM_TAG}\nADD app.tar.gz .",
    "images": [
        {
            "from": {
                "kind": "ImageStreamTag",
                "name": "${NAME}-build:latest"
            },
            "paths": [
                {
                    "sourcePath": "/opt/app-root/app.tar.gz",
                    "destinationDir": "."
                }
            ]
        }
    ]
}

The runtime image also has triggers to rebuild automatically when build image is updated in the projects internal image stream or when the dotnet-20-runtime-rhel7 base image updates.

There is also a deployment defined for the runtime image. A deployment is not necessary for the build image.

The use of these triggers means that any object in the chain will be rebuilt as necessary when images or code is updated.

Report a bug