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.
If you don't already have a Google Account (Gmail or Google Apps), you must create one. Sign-in to Google Cloud Platform console (console.cloud.google.com) and create a new project:
Remember the project ID, a unique name across all Google Cloud projects (the name above has already been taken and will not work for you, sorry!). It will be referred to later in this codelab as PROJECT_ID
.
Next, you'll need to enable billing in the Cloud Console in order to use Google Cloud resources.
Running through this codelab shouldn't cost you more than a few dollars, but it could be more if you decide to use more resources or if you leave them running (see "cleanup" section at the end of this document).
New users of Google Cloud Platform are eligible for a $300 free trial.
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.
From the GCP Console click the Cloud Shell icon on the top right toolbar:
Then click "Start Cloud Shell":
It should only take a few moments to provision and connect to the environment:
This virtual machine is loaded with all the development tools you'll need. It offers a persistent 5GB home directory, and runs on the Google Cloud, greatly enhancing network performance and authentication. Much, if not all, of your work in this lab can be done with simply a browser or your Google Chromebook.
Once connected to the cloud shell, you should see that you are already authenticated and that the project is already set to your PROJECT_ID.
Run the following command in the cloud shell to confirm that you are authenticated:
gcloud auth list
Command output
Credentialed accounts: - <myaccount>@<mydomain>.com (active)
gcloud config list project
Command output
[core] 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 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 which simply prints Hello World in a new tab.
Once you verified that the app is running, press Ctrl+C to shut down the app.
Now, publish the app to get a self-contained DLL using the dotnet publish
command.
dotnet publish -c Release
Running publish
displays some messages with a successfully published DLL at the end of the process.
...
HelloWorldAspNetCore -> /home/atameldev/HelloWorldAspNetCore/bin/Release/netcoreapp2.1/HelloWorldAspNetCore.dll
Navigate to the the publish folder for the next step.
cd bin/Release/netcoreapp2.1/publish/
Next, prepare your app to run as a container. The first step is to define the container and its contents.
In the publish
directory and 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).
FROM gcr.io/google-appengine/aspnetcore:2.1 ADD ./ /app ENV ASPNETCORE_URLS=http://*:${PORT} WORKDIR /app ENTRYPOINT [ "dotnet", "HelloWorldAspNetCore.dll"]
Dockerfile
builds on the official Google App Engine image for ASP.NET Core apps, which is already configured to run .NET Core apps and adds the app files and the tools necessary to run the app from the directory. App Engine will replace ${PORT}
with 8080.
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
. We will build the image next but before that, let's set the PROJECT_ID
as an environment variable and test that it is set as follows:
export PROJECT_ID=$(gcloud config get-value core/project)
Test that it is set as follows:
echo ${PROJECT_ID} yourproject-XXXX
Now, let's build the image:
docker build -t gcr.io/${PROJECT_ID}/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 gcr.io/yourproject-XXXX/hello-dotnet v1 gcr.io/google-appengine/aspnetcore 2.1
Test the image locally with the following command which will run a Docker container as a daemon on port 8080 from your newly-created container image:
docker run -d -p 8080:8080 gcr.io/${PROJECT_ID}/hello-dotnet:v1
You can see the container running:
docker ps CONTAINER ID IMAGE fb9c45661d87 gcr.io/jump-to-cloud18-eze-1601/hello-dotnet:v1
And again take advantage of the Web preview feature of CloudShell :
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. First, get the container id. In this example, your app was running as Docker process ced2872b26fc
:
docker ps CONTAINER ID IMAGE ced2872b26fc gcr.io/PROJECT_ID/hello-dotnet:v1
Stop the container.
docker stop ced2872b26fc ced2872b26fc
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) :
gcloud docker -- push gcr.io/${PROJECT_ID}/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: https://console.cloud.google.com/storage/browser/ (the full resulting link should be of this form: https://console.cloud.google.com/project/PROJECT_ID/storage/browser/).
To create a new cluster with Istio enabled with mutual TLS between sidecars enforced by default, run this command:
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
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:
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 --overwrite
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:
NAME STATUS AGE ISTIO-INJECTION default Active 34m enabled istio-system Active 32m kube-public Active 34m kube-system Active 34m
First, ensure the following Kubernetes services are deployed:
istio-pilot
istio-ingressgateway
,istio-egressgateway
istio-telemetry
istio-policy
istio-citadel
istio-sidecar-injector
prometheus
kubectl get svc -n istio-system
Your output should look like the following:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) istio-citadel ClusterIP 30.0.0.119 <none> 8060/TCP,9093/TCP istio-egressgateway ClusterIP 30.0.0.11 <none> 80/TCP,443/TCP istio-ingressgateway LoadBalancer 30.0.0.39 9.111.255.245 80:31380/TCP,443:31390/TCP,31400:31400/TCP istio-pilot ClusterIP 30.0.0.136 <none> 15003/TCP,15005/TCP,15007/TCP,15010/TCP,15011/TCP,8080/TCP,9093/TCP istio-policy ClusterIP 30.0.0.242 <none> 9091/TCP,15004/TCP,9093/TCP istio-statsd-prom-bridge ClusterIP 30.0.0.111 <none> 9102/TCP,9125/UDP istio-telemetry ClusterIP 30.0.0.246 <none> 9091/TCP,15004/TCP,9093/TCP,42422/TCP prometheus ClusterIP 30.0.0.253 <none> 9090/TCP istio-sidecar-injector ClusterIP 10.23.242.122<none> 443/TCP
Next, make sure that the corresponding Kubernetes pods are deployed and all containers are up and running:
istio-pilot-*
istio-ingressgateway-*
istio-egressgateway-*
istio-policy-*
istio-telemetry-*
istio-citadel-*
istio-sidecar-injector-*
prometheus-*
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-7bdc7775c7-22dxq 1/1 Running istio-egressgateway-78dd788b6d-ld4qx 1/1 Running istio-ingressgateway-7dd84b68d6-smqbt 1/1 Running istio-pilot-d5bbc5c59-sv6ml 2/2 Running istio-policy-64595c6fff-sqbz7 2/2 Running istio-sidecar-injector-dbd67c88d-4jxqj 1/1 Running istio-statsd-prom-bridge-949999c4c-fbfzg 1/1 Running istio-telemetry-cfb674b6c-kk98w 2/2 Running prometheus-86cb6dd77c-z2tmq 1/1 Running istio-pilot-2275554717-93c43 2/2 Running
Now you've verified that Istio is installed and running, you can deploy the ASP.NET Core app.
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 metadata: name: aspnetcore-service labels: app: aspnetcore spec: ports: - port: 8080 name: http selector: app: aspnetcore --- apiVersion: extensions/v1beta1 kind: Deployment metadata: name: aspnetcore-v1 spec: replicas: 1 template: metadata: labels: app: aspnetcore version: v1 spec: containers: - name: aspnetcore image: gcr.io/YOUR-PROJECT-ID/hello-dotnet:v1 imagePullPolicy: IfNotPresent ports: - 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
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:
apiVersion: networking.istio.io/v1alpha3 kind: Gateway metadata: name: aspnetcore-gateway spec: selector: istio: ingressgateway # use istio default controller servers: - port: number: 80 name: http protocol: HTTP hosts: - "*"
Create a aspnetcore-virtualservice.yaml
file to define the VirtualService:
apiVersion: networking.istio.io/v1alpha3 kind: VirtualService metadata: name: aspnetcore-virtualservice spec: hosts: - "*" gateways: - aspnetcore-gateway http: - 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:
gateway.networking.istio.io "aspnetcore-gateway" created
Next, run the following command to deploy the VirtualService:
kubectl apply -f aspnetcore-virtualservice.yaml
The command produces the following output:
virtualservice.networking.istio.io "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[?(@.name=="http2")].port}') export GATEWAY_URL=$INGRESS_HOST:$INGRESS_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.
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.
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
To delete Istio:
kubectl delete -f install/kubernetes/istio-demo-auth.yaml
To confirm that Istio is gone:
kubectl get pods -n istio-system
gcloud container clusters delete hello-istio