ASP.NET Core is an open-source and cross-platform framework for building modern cloud-based and internet-connected applications using the C# programming language.

Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications. Istio is an open framework for connecting, securing, managing and monitoring services.

In this first part of the lab, you deploy a simple ASP.NET Core app to Kubernetes running on Google Kubernetes Engine (GKE) and configure it to be managed by Istio.

In the second part of the lab, you further explore features of Istio such as metrics, tracing, dynamic traffic management, fault injection, and more.

What you'll learn

What you'll need

How will you use this tutorial?

Read it through only Read it and complete the exercises

How would rate your experience with Google Cloud Platform?

Novice Intermediate Proficient

Codelab-at-a-conference setup

By using a kiosk at Google I/O, a test project has been created and can be accessed by using going to:

These temporary accounts have existing projects that are set up with billing so that there are no costs associated for you with running this codelab.

Note that all these accounts will be disabled soon after the codelab is over.

Use these credentials to log into the machine or to open a new Google Cloud Console window Accept the new account Terms of Service and any updates to Terms of Service.

When presented with this console landing page, please select the only project available. Alternatively, from the console home page, click on "Select a Project" :

Start Cloud Shell

While Google Cloud can be operated remotely from your laptop, in this codelab you use Google Cloud Shell, a command line environment running in Google Cloud.

Activate Cloud Shell

  1. From the Cloud Console, click Activate Cloud Shell .

If you've never started Cloud Shell before, you'll be presented with an intermediate screen (below the fold) describing what it is. If that's the case, click Continue (and you won't ever see it again). Here's what that one-time screen looks like:

It should only take a few moments to provision and connect to Cloud Shell.

This virtual machine is loaded with all the development tools you'll need. It offers a persistent 5GB home directory and runs in Google Cloud, greatly enhancing network performance and authentication. Much, if not all, of your work in this codelab can be done with simply a browser or your Chromebook.

Once connected to Cloud Shell, you should see that you are already authenticated and that the project is already set to your project ID.

  1. Run the following command in Cloud Shell to confirm that you are authenticated:
gcloud auth list

Command output

 Credentialed Accounts
*       <my_account>@<>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`
gcloud config list project

Command output

project = <PROJECT_ID>

If it is not, you can set it with this command:

gcloud config set project <PROJECT_ID>

Command output

Updated property [core/project].

In Cloud Shell prompt, you can verify that the dotnet command line tool is already installed by checking its version. This should print the version of the installed dotnet command line tool:

dotnet --version

Next, create a new skeleton ASP.NET Core web app.

dotnet new mvc -o HelloWorldAspNetCore

This should create a project and restore its dependencies. You should see a message similar to below.

Restore completed in 11.44 sec for HelloWorldAspNetCore.csproj.

Restore succeeded.

We're almost ready to run our app. Navigate to the app folder.

cd HelloWorldAspNetCore

Finally, run the app.

dotnet run --urls=http://localhost:8080

Application starts listening on port 8080.

Hosting environment: Production
Content root path: /home/atameldev/HelloWorldAspNetCore
Now listening on: http://[::]:8080
Application started. Press Ctrl+C to shut down.

To verify that the app is running, click on the web preview button on the top right and select ‘Preview on port 8080'.


You'll see the default ASP.NET Core webpage:

Once you verify that the app is running, press Ctrl+C to shut down the app.

Next, prepare your app to run as a container. The first step is to define the container and its contents.

In the base directory of the app, create a Dockerfile to define the Docker image.

touch Dockerfile

Add the following to Dockerfile using your favorite editor (vim, nano,emacs or Cloud Shell's code editor).

# Use Microsoft's official build .NET image.
FROM AS build

# Install production dependencies.
# Copy csproj and restore as distinct layers.
COPY *.csproj ./
RUN dotnet restore

# Copy local code to the container image.
COPY . ./

# Build a release artifact.
RUN dotnet publish -c Release -o out

# Use Microsoft's official runtime .NET image.
FROM AS runtime
COPY --from=build /app/out ./

# Make sure the app binds to port 8080

# Run the web service on container startup.
ENTRYPOINT ["dotnet", "HelloWorldAspNetCore.dll"]

One important configuration included in your Dockerfile is the port on which the app listens for incoming traffic (8080). This is accomplished by setting the ASPNETCORE_URLS environment variable, which ASP.NET Core apps use to determine which port to listen to.

Save this Dockerfile. Now, let's build the image:

docker build -t${GOOGLE_CLOUD_PROJECT}/hello-dotnet:v1 .

Once this completes (it'll take some time to download and extract everything), you can see the image is built and saved locally:

docker images

REPOSITORY                             TAG   v1            

Test the image locally with the following command which will run a Docker container locally on port 8080 from your newly-created container image:

docker run -p 8080:8080${GOOGLE_CLOUD_PROJECT}/hello-dotnet:v1

And again take advantage of the Web preview feature of CloudShell :

Screenshot from 2015-11-03 17:20:22.png

You should see the default ASP.NET Core webpage in a new tab.

Once you verify that the app is running fine locally in a Docker container, you can stop the running container by Ctrl-> C.

Now that the image works as intended you can push it to the Google Container Registry, a private repository for your Docker images accessible from every Google Cloud project (but also from outside Google Cloud Platform) :

docker push${GOOGLE_CLOUD_PROJECT}/hello-dotnet:v1

If all goes well and after a little while, you should be able to see the container image listed in the Container Registry section. At this point, you now have a project-wide Docker image available which Kubernetes can access and orchestrate as you'll see in a few minutes.

If you're curious, you can navigate through the container images as they are stored in Google Cloud Storage by following this link: (the full resulting link should be of this form:

To create a new cluster with Istio enabled with mutual TLS between sidecars enforced by default, run this command. You can change the region to somewhere close to you, if you like:

gcloud beta container clusters create hello-istio \
--project=${PROJECT_ID} --addons=Istio --istio-config=auth=MTLS_STRICT \
--cluster-version=latest --machine-type=n1-standard-2 --num-nodes=4 \
--region europe-west1

Wait a few moments while your cluster is set up for you. It will be visible in the Kubernetes Engine section of the Google Cloud Platform console.

It also creates the istio-system namespace along with the required RBAC permissions, and deploys the five primary Istio control plane components:

Automatic sidecar injection

To start using Istio, you don't need to make any changes to the application. When you configure and run the services, Envoy sidecars are automatically injected into each pod for the service.

For that to work, you need to enable sidecar injection for the namespace (‘default') that you use for your microservices. You do that by applying a label:

kubectl label namespace default istio-injection=enabled

To verify that the label was successfully applied, run the following command:

kubectl get namespace -L istio-injection

The output confirms that sidecar injection is enabled for the default namespace:

default        Active    34m       enabled
istio-system   Active    32m
kube-public    Active    34m
kube-system    Active    34m

First, ensure the following Kubernetes services are deployed:

kubectl get svc -n istio-system

Your output should include the following services:

Next, make sure that the corresponding Kubernetes pods are deployed and all containers are up and running:

kubectl get pods -n istio-system

After all the pods are marked as running, you can proceed. You might have some post-install and cleanup pods marked as completed, instead of running, and that's ok.

NAME                                      READY     STATUS      
istio-citadel-7c4864c9d5-xv4c5            1/1       Running
istio-cleanup-secrets-zm6sd               0/1       Completed
istio-egressgateway-6f96d6cb7f-grl6n      1/1       Running
istio-galley-698f5c74d6-w45nk             1/1       Running
istio-ingressgateway-54b99b688b-hjdtj     1/1       Running
istio-pilot-57f8d655f4-86q7t              2/2       Running
istio-policy-78cc586999-p4nnl             2/2       Running
istio-sidecar-injector-6555557c7b-hlfwx   1/1       Running
istio-telemetry-77594fdf5d-css4n          2/2       Running
promsd-ff878d44b-7nlms                    2/2       Running

Now you've verified that Istio is installed and running, you can deploy the ASP.NET Core app.

Deployment and Service

First, create an aspnetcore.yaml file using your favorite editor (vim, nano,emacs or Cloud Shell's code editor) and define the Kubernetes Deployment and Service for the app:

apiVersion: v1
kind: Service
  name: aspnetcore-service
    app: aspnetcore
  - port: 8080
    name: http
    app: aspnetcore
apiVersion: extensions/v1beta1
kind: Deployment
  name: aspnetcore-v1
  replicas: 1
        app: aspnetcore
        version: v1
      - name: aspnetcore
        imagePullPolicy: IfNotPresent
        - containerPort: 8080

The contents of the file are standard Deployments and Services to deploy the application and don't contain anything Istio-specific.

Deploy the services to the default namespace with kubectl:

kubectl apply -f aspnetcore.yaml
service "aspnetcore-service" created
deployment.extensions "aspnetcore-v1" created

Verify that pods are running:

kubectl get pods
NAME                          READY     STATUS    RESTARTS   AGE
aspnetcore-v1-6cf64748-mddb   2/2       Running   0          34s

Gateway and VirtualService

To allow ingress traffic to reach the mesh you need to create a Gateway and a VirtualService.

A Gateway configures a load balancer for HTTP/TCP traffic, most commonly operating at the edge of the mesh to enable ingress traffic for an application. A VirtualService defines the rules that control how requests for a service are routed within an Istio service mesh.

Create a aspnetcore-gateway.yaml file to define the Gateway:

kind: Gateway
  name: aspnetcore-gateway
    istio: ingressgateway # use istio default controller
  - port:
      number: 80
      name: http
      protocol: HTTP
    - "*"

Create a aspnetcore-virtualservice.yaml file to define the VirtualService:

kind: VirtualService
  name: aspnetcore-virtualservice
  - "*"
  - aspnetcore-gateway
  - route:
    - destination:
        host: aspnetcore-service

Run the kubectl command to deploy the Gateway with:

kubectl apply -f aspnetcore-gateway.yaml

The command produces the following output: "aspnetcore-gateway" created

Next, run the following command to deploy the VirtualService:

kubectl apply -f aspnetcore-virtualservice.yaml

The command produces the following output: "aspnetcore-virtualservice" created

Verify that everything is running:

kubectl get gateway
NAME                      AGE
aspnetcore-gateway   28s
kubectl get virtualservice
NAME                             AGE
aspnetcore-virtualservice   33s

Congratulations! You have just deployed an Istio-enabled application. Next, you see the application in use.

You can finally see the application in action. You need to get the external IP and port of the gateway. It's listed under EXTERNAL-IP:

kubectl get svc istio-ingressgateway -n istio-system

Export the external IP and port to a GATEWAY_URL variable:

export INGRESS_HOST=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

export INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?("http2")].port}')


Use curl to test out the app. The service should respond with a response code of 200:

curl -o /dev/null -s -w "%{http_code}\n" http://${GATEWAY_URL}/

Alternatively, you can open up the browser, navigate to http://<gatewayurl> to view the app:

You just deployed a simple ASP.NET Core app to Kubernetes running on Google Kubernetes Engine (GKE) and configured it to be managed by Istio.

You might be wondering "What's the benefit of Istio?". That's a great question. So far, there's no advantage to having Istio manage this app. In the second part of the lab, we will further explore features of Istio, such as metrics, tracing, dynamic traffic management, service visualization, and fault injection.

Next Steps


This work is licensed under a Creative Commons Attribution 2.0 Generic License.

If you're not continuing to the second part of the lab, you can delete the app and uninstall Istio or you can simply delete the Kubernetes cluster.

Delete the app

To delete the app:

kubectl delete -f aspnetcore-gateway.yaml
Kubectl delete -f aspnetcore-virtualservice.yaml
kubectl delete -f aspnetcore.yaml

To confirm that the app is gone:

kubectl get gateway 
kubectl get virtualservices 
kubectl get pods

Uninstall Istio

To delete Istio:

kubectl delete -f install/kubernetes/istio-demo-auth.yaml

To confirm that Istio is gone:

kubectl get pods -n istio-system

Delete Kubernetes cluster

gcloud container clusters delete hello-istio