Skip to content

Latest commit

 

History

History
593 lines (524 loc) · 29.7 KB

ServiceFabricNative.md

File metadata and controls

593 lines (524 loc) · 29.7 KB
Raw

ContainersSFLab - Service Fabric Native application

The instructions below walk you through packaging an existing ASP.NET application for Service Fabric clusters, using the Service Fabric Native application model.

For more info about Service Fabric application models, look here: https://docs.microsoft.com/en-us/azure/service-fabric/service-fabric-technical-overview#application-and-service-concepts

Requirements for running the lab are

  • Windows 10 Enterprise or Professional Edition or Windows Server 2016
  • Docker for Windows
  • Visual Studio 2017 15.7
  • Service Fabric SDK 3.1 and Service Fabric Runtime 6.2
  • An Azure subscription: If you do not have one, you can get a trial subscription here:https://azure.microsoft.com/en-us/free/

Containerize an existing ASP.NET application using Visual Studio and Service Fabric

Lab Overview

In this lab, you will be guided through the following tasks:

  1. Build a Docker container for Windows, with an existing ASP.NET web application

  2. Create an Azure Container Registry, and push your container to a registry

  3. Create an Azure Service Fabric application with your container

  4. Deploy your application to Azure Service Fabric

Build a Docker container for Windows, with an existing ASP.NET web application

Goal: The goal of this section is to have an ASP.NET application running in a Docker container on your Windows 10 developer machine.

Process

Step Procedure
Run the application Run the existing ASP.NET application to verify its functionality, using Visual Studio and IIS Express.
Create a Docker container Create a docker container.
Run the application in a container Run and debug the application running in a container, using Visual Studio.

Run the Application

In this section we will test the ASP.NET application using Visual Studio and IIS Express.

Step Action Result
1 Open the solution eShopLegacyWebForms.sln, which you will find in the \Lab\eShopLegacyWebFormsSolution folder on the desktop.

Note
Visual Studio will ask for login, choose Not now and choose a theme.		 Visual Studio will open, and you will see one project with an ASP.NET MVC application in Visual Studio.
2 Expand the Default.aspx file in the Solution Explorer, then open the Default.aspx.cs file in Visual Studio and set a breakpoint at line 25. This will break the application once a browser requests the home page.
3 Change the Solution Configuration to Debug and press F5 to start debugging the application. The application will now build, and Edge will open with the application when it’s ready.
4 When the breakpoint is hit, click F5 to continue code execution. The applications home page shows up in Edge.
5 The application simulates a simple web shop administrative interface. Feel free to browse around the application to see details of the various products and some of the functionality. Note: The application is setup to use mock data loaded from source files, so all changes will be reverted once the debug session closes.
6 Press Shift+F5 to stop the debugging Debugging stops.

Completion

You’ve now complete debugging an ASP.NET application using Visual Studio and IIS Express.

Create a Docker container

In this section we will create a docker container image to run the ASP.NET application eShopLegacyWebForms, which requires Internet Information Server (IIS) to be running in the container.

Step Action Result
1 Publish eShopLegacyWebForms application to a folder from Visual Studio by:

1. Right-Clicking the eShopLegacyWebForms project and choose Publish
2. Choose Folder
3. Click Publish		 The web application is now published to a folder and ready to be deployed in to a container image.
2 Open PowerShell and change directory to “C:\Users\Administrator\Desktop\
Lab\eShopLegacyWebFormsSolution\src\eShopLegacyWebForms”
3 Create a new DockerFile (no file extension) and open it in Notepad, by running the following commands:

1. New-Item Dockerfile
2. Notepad Dockerfile
3. A blank Notepad will show up.
4 Add the following content:

FROM microsoft/aspnet:4.7.1-windowsservercore-ltsc2016
COPY bin/Release/Publish /inetpub/wwwroot
5 Save and close the file The Dockerfile contains instructions for the docker engine on how to build a container, when running the “docker build” command in this directory.
6 In PowerShell run the command
“docker build . -t eshopweb:1.0”
in the directory “C:\Users\Administrator\Desktop\
Lab\eShopLegacyWebFormsSolution\src\eShopLegacyWebForms”		 This command will tell the Docker host to build a container image and tag it eshopweb:1.0, using the instructions in the Dockerfile.
7 Run the command docker images to see the container images cached on your machine You should see an image with the repository: eshopweb and the tag: 1.0.

Completion

You’ve now published the ASP.NET application eShopLegacyWebForms and built a docker container image with the application.

Run the application in a container

Step Action Result
1

Create an instance of the container and run it, by running the following command in PowerShell:

docker run -p 80:80 -d --name eshoptest eshopweb:1.0

 This creates and starts a container, exposing port 80 on the local host.
2 Once the command return, open Edge and browse to http://localhost. You should now see the application being served from the container.
3 Stop the container by running the command docker stop eshoptest in PowerShell This stops the container and persists the state and configuration. You can then restart the container at a later point.
4 Remove the container by running the command docker rm eshoptest in PowerShell This command will remove the container state and configuration. We will do this as in the next step we create a new instance of the container with a different configuration.
5

The application has a feature to add an environment variable to the front-page title.

Create a new configuration of the container image, by running the following command in PowerShell:

docker run -p 80:80 -d --name eshoptest -e eShopTitle=MyTitle eshopweb:1.0

Note:

This feature is implemented in the Site.Master.cs file.

 Environment variables is a common way of passing configurations to containers. The -e parameter is used with docker to pass environment variables to containers.
6 Once the command returns, open Edge and browse to http://localhost. You should now see the application title using your environment variable.
7

You can run commands inside a running container’. Output the environment variables from the container by running the following commands in PowerShell:

docker exec eshoptest cmd.exe /C SET

 You will see all the environment variables in the container being output.
8

Let’s stop and remove the container:

  1. docker stop eshoptest

  2. docker rm eshoptest

Completion

In this section of the lab, we created a container image with our application, and ran it. Finally, we used environment variables to configure the application running in the container.

Create an Azure Container Registry, and push your container to a registry

Goal: The goal of this section is to publish the container image to a private Azure Container Registry.

Azure Subscription

If you do not have one, you can get a trial subscription here: https://azure.microsoft.com/en-us/free/

Process

Step Procedure
Create a container registry

Create a private container registry using the Azure Container Registry service.

Note: This requires an Azure account
Build, tag and push the container image Create a production ready container image and push it to the registry.
Pull the container image and run it locally Pull the production ready image from the container registry and run it.

Create a container registry

In this section we will create a private container registry in Azure using Azure Container Registry.

Step Action Result
1 Browse to https://shell.azure.com/ and sign-in to your Azure subscription. If you do not have one, you can get a trial subscription here: https://azure.microsoft.com/en-us/free/
2

Create a new resource group:

az group create --name [insert rg name] --location eastus

Note: Substitute the [insert rg name] with the name for your Resource Group

 az will output information about the resource group.
3

Create a container registry in that resource group:

az acr create --resource-group [insert rg name] --name [insert acr name] --sku Basic --admin-enabled

Note: Substitute the [insert acr name] with the name for your registry name

 az will output the information about the newly created acr.
4

Retrieve the credentials to sign-in to the container registry, and note these to be used later:

az acr credential show --name [insert acr name]

Note: Substitute the [insert acr name] with the name for your registry name

 az will output the passwords and login names for the registry, which we will use later in the lab.

Completion

In this section of the lab, we’ve created a private container registry as a repository to store your container images.

Build, tag and push the container

In this section we will prepare our container image to be uploaded, by tagging it and upload the image to our registry.

Step Action Result
1

Open PowerShell and run the following command to tag the image:

docker tag eshopweb:1.0 [insert acr name].azurecr.io/eshopweb:1.0

Note:

The registry part of the container image tag should match the name of your container registry.

 This command creates a container image tag with the container registry name and version of the container image.
2

Run the following command to login to your container registry:

docker login [insert acr name].azurecr.io

Note:

To retrieve the login server, username and password, see above section
3

Push the container image to your registry:

docker push [insert acr name].azurecr.io/eshopweb:1.0

 This will start uploading the container image layers to you Azure Container Registry.

Completion

In this section of the lab, we’ve tagged our container image and uploaded it to our private container registry, ready to be deployed to any container host.

Pull the container image and run it locally

In this section we’ll do a final validation of being able to pull down the container image.

Note: If you don’t want to wait for the image to be pushed to the registry, skip step 1 and 2 in this section.

Step Action Result
1

Since we already have the image locally, let’s start by removing the local copy. Still in PowerShell, run this command:

docker rmi [insert acr name].azurecr.io/eshopweb:1.0

The output of the command should read: Untagged: mycontainerregistry.azurecr.io\eshopweb:1.0

Since this is another tag on top of an existing image, the image is not being deleted, just the tag.
2

To pull the container run this command:

docker pull [insert acr name].azurecr.io/eshopweb:1.0

 The pull will complete instantaneously, as the image files, which this tag refers to are already on disc.
3

Let’s run the container and validate it works:

docker run -p 80:80 --name eshopweb -e eShopTitle=MyTitle [insert acr name].azurecr.io/eshopweb:1.0
4 Once the command returns, open Edge and browse to http://localhost. You should now see the application.
5

Finally, let’s clean-up, by running the following commands in PowerShell in the directory C:\Users\Administrator\Desktop\Lab:

  1. by stopping the container: docker stop eshopweb

  2. Remove the container: docker rm eshopweb

  3. Reset the repository

    1. git clean -df

    2. git reset --hard

Note: You need to do the clean-up to continue with the lab

 All cleaned-up and good to go

Completion

In this section of the lab, we’ve pulled down the container image form our private container registry, simulating a deployment, and validated the container can be run and the application works.

Create an Azure Service Fabric application with your container

Goal: The goal of this section is to have the container running as a service in a Service Fabric application.

Process

Step Procedure
Create a Service Fabric Application We will use Visual Studio to create a Service Fabric application hosting the container.
Run the container as a service in Service Fabric We will set up a local development cluster and deploy the containerized application to the local cluster.
Apply container policies and upgrade We will apply container resource policies and parameters for configuration. Finally, we will upgrade the running application in the cluster.

Create a Service Fabric Application

In this section we will create a Service Fabric application with the container as a service, and configure it.

Step Action Result
1 Open the solution eShopLegacyWebForms.sln, which you will find in the \Lab\eShopLegacyWebFormsSolution folder on the desktop. The application code will open in Visual Studio 2017.
2 Right-Click the project file and choose Add -> Container Orchestrator Supprt. Choose Service Fabric. Visual Studio 2017 will now create the required Dockerfile for your container image, as well as a Service Fabric application project in the solution in Visual Studio.
3

To instruct Service Fabric to open port 80 for the service (our container), like we did in the previous docker commands, we must specify the port to use in the ServiceManifest.xml file.

  1. The ServiceManifest.xml file should already be open

  2. Specify the port to use for the endpoint in the <Endpoint> element:

<Endpoint Name="eShopLegacyWebFormsTypeEndpoint" Port="80"/>

  1. Save the file

Note:

If no endpoint is specified, Service Fabric will assign a random endpoint from a predefined pool of ports.

 The endpoint is bound to the service, which will host the container in Service Fabric. This configuration will ensure that Service Fabric attaches a port to the service process when it’s running.
4

To instruct Service Fabric to map port 80 of the container to the endpoint we specified above, we must create a PortBinding configuration in the ApplicationManifest.xml file.

  1. In the ApplicationPackageRoot folder under the Application project, open the ApplicationManifest.xml file

  2. Verify the following configuration, as part of the < ContainerHostPolicies > element:

<PortBinding ContainerPort="80" EndpointRef="eShopLegacyWebFormsTypeEndpoint" />

  1. Save the file

 This configuration ensures that the port exposed by the container, will be mapped to the endpoint of the service. The end result is similar to the -p 80:80 command we used when running the container previous.
5

Finally, we’ll specify an environment variable to pass to the container.

  1. In the ServiceManifest.xml file, add the following element in the CodePackage element to pass an environment variable to the container:

<EnvironmentVariables>

<EnvironmentVariable Name="eShopTitle" Value="on SF!"/>

</EnvironmentVariables>

  1. Save the file

Note:

If the environment variable value you put in is too long a string, it will cause the web site to not show any title – so be kind

 This environment variable configuration will be used for the front page of the web application.

Completion

In this section of the lab, we’ve created a Service Fabric application and configured the container to run in a Service Fabric cluster.

Run the container as a service in Service Fabric

In this section we will run the container in Service Fabric on our developer machine.

Step Action Result
1

Service Fabric cluster can run on Windows 10, and the SDK provides cluster configuration scripts which supports setting up clusters of one node for development purposes. Let’s start by creating a one node cluster.

Right-click the Service Fabric Local Cluster Manager in the task bar and select Start Local Cluster

A Service Fabric cluster will now be created on your developer machine.

We will be using a one node cluster in this lab, as additional nodes will only add overhead to the developer experience and is usually only needed for debugging failover scenarios.
2 Open Service Fabric Explorer using the desktop link and choose Connect to localhost

Service Fabric Explorer is your management UI for any Service Fabric cluster, locally, in Azure or on-premises.

Service Fabric explorer let you get information about your cluster, application and services and do administrative commands against the cluster.
3

Next go back to Visual Studio 2017 to publish the application:

  1. Right-click the Service Fabric application project and select Publish to publish the application to the local Service Fabric cluster.

  2. Choose PublishProfiles\Local.1Node.xml as the Target profile.

  3. Click Publish

 Visual Studio will build the container and deploy the application to Service Fabric. The Service Fabric cluster will then pull the container image form the local cache and run it as a Service in Service Fabric.
4 Once the deployment is completed, you can browse to http://localhost to see the website running in SF. In this scenario we are just publishing the container, however you can also debug the application code in a container running on Service Fabric, simply by pressing F5.
5 Go to Service Fabric Explorer, which will now show you one Application deployed in the cluster.

Completion

In this section of the lab, we’ve created a local Service Fabric cluster and deployed our application in a container to the cluster.

Apply container policies and upgrade the application

In this section we will enable parameterization of our application configuration and apply resource policies to the container. We will also roll-out an upgrade to the Service Fabric application.

Step Action Result
1

Docker and Service Fabric can control the amount of resources containers can use in a cluster. To specify the amount of memory and CPU for our container do the following:

  1. In the ApplicationPackageRoot folder under the Application project, open the ApplicationManifest.xml file

  2. Insert the following configuration, as part of the < Policies > element:

<ServicePackageResourceGovernancePolicy CpuCores="1" MemoryInMB="1024" />

  1. Save the file

 This will make sure this container gets a single CPU core and 1GB of memory assigned in the cluster. Service Fabric uses this enforcement to place containers in the cluster.
2

We also want to have a single configuration file for changing configuration for our container across environments. In Service Fabric we will use the ApplicationParameter files to do this. To parameterize the environment variable, do the following:

  1. Open the ApplicationManifest.xml file

  2. Insert the following to override the environment variable in the ServiceManifest.xml file as part of the <ServiceManifestImport> element:

<EnvironmentOverrides CodePackageRef="Code">

<EnvironmentVariable Name="eShopTitle" Value="[eShopLegacyWebForms_eShopTitle]" />

</EnvironmentOverrides>

  1. The value specified in square bracket `[]` is a reference to a parameter, which we will also have to add to the file, as part of the <Parameters> element. We will set the default value to be an empty string.

<Parameter Name="eShopLegacyWebForms_eShopTitle" DefaultValue="" />

  1. Save the file
3

Now that we have defined the environment variable to be overridden by a parameter, let’s specify the parameter:

  1. Open the ApplicationParameters folder and the file Local.1Node.xml. This is the file which will be used when we publish to our local cluster.

  2. Add the following to the <Parameters> element:

<Parameter Name="eShopLegacyWebForms_eShopTitle" Value="One" />

  1. Save the file

 Parameter files is a concept understood by Visual Studio and VSTS. If you will be using PowerShell or other means to deploy, Service Fabric accepts parameters as a hash table.
4

Let’s go ahead and upgrade the application in the local cluster:

  1. Right-click the Service Fabric application project and select Publish to publish the application to the local Service Fabric cluster.

  2. Choose PublishProfiles\Local.1Node.xml as the Target profile.

  3. Check Upgrade the application

  4. Click Manifest Version

  5. Change the version of the ApplicationType to 2.0 (New Version)

  6. Click Save

  7. Click Publish

 All parts of a Service Fabric application are versioned. This enables the platform to only upgrade the specific parts of the application which are being changed as part of an upgrade.
5

Open Service Fabric Explorer using the desktop link and choose Connect to localhost.

  1. Click Applications and notice the application is now version 2.0.

  2. Click Cluster and Metrics and notice the resource capacity overview in the cluster.

 If the cluster had consisted of multiple nodes, the upgrade would have taken a while as each node gets updated to completion, and the upgrade would only move forward if no errors occurred. If an error occurred, the upgrade would automatically roll-back, leaving the application up and running.
6 Open Edge and browse to http://localhost to see the changes.

Completion

In this section of the lab, we’ve parameterized our configuration, applied resource governance and upgraded our application in the Service Fabric cluster.