The Children's Guide to Kubernetes is a simple, gentle answer a father gives his daughter, when she inquisitively asked about Kubernetes. It was written by Matt Butcher on the DEIS blog.
We loved the story and the imagery in it and thought the characters from the Illustrated Guide would make for an interesting demo. The demo has a few services, each of which represent an individual character in the story, as well as some we added. Each service is written in a different language, showing how the Azure Kubernetes Service (AKS) cluster can run anything you can bring it.
Here's a short list of all the things you'll need to do. Don't worry - you'll be up and running in about thirty minutes.
- An Azure subscription. You can Sign up for Free and see for yourself how Azure Kubernetes Service (AKS) is the best place for developers using Kubernetes.
- An Azure Kubernetes Service (AKS) Cluster, enabled with Http Application Routing (this is on by default when you create a cluster via the Azure portal).
- Important note: if your AKS cluster has RBAC enabled, you will need to run the following command to have
captainkube
able to read the information in the cluster:kubectl create clusterrolebinding default-view --clusterrole=view --serviceaccount=phippyandfriends:default
.
- Important note: if your AKS cluster has RBAC enabled, you will need to run the following command to have
- An Azure Container Registry instance (or a Docker Hub account if you prefer to use Docker Hub). If you opt to use Azure Container Registry, make sure you configure RBAC access so that AKS has the proper role assignment to access your ACR.
- You'll need to install a few tools handy for developing with containers and Kubernetes, and the Azure CLI:
- The Azure CLI
- Helm and Draft are also required, as they enable deploying and debugging code in Kubernetes.
- Visual Studio Code and the Kubernetes extension for it would also be great to have.
To get started, follow these simple steps.
The Phippy and Friends repository is public. Just clone it to your local machine and open the folder up in Visual Studio Code to get started.
git clone https://github.com/Azure/phippyandfriends.git
cd phippy-demo
code .
A few of the services will provide HTML UIs. To enable external access, Ingress needs to be set up on each of these services using the external DNS of the cluster. Don't worry, though, this is easy. You can use VS Code's integrated terminal or the Cloud Shell tools in VS Code to run this az
command line call, which will get your AKS cluster's external DNS.
az aks show -n <your cluster name> -g <your resource group name> --query addonProfiles.httpApplicationRouting.config.HTTPApplicationRoutingZoneName
You can also get the DNS from the Azure portal if you prefer.
We'll be deploying the parrot service first (more on that in a moment), so let's take a look at the values.yaml
file for parrot. The values.yaml
file is where you can customize your service, release, deployment, and in our case, ingress settings. Find the basedomain
property.
Change the value of the basedomain
property to match the DNS for your AKS cluster.
If you want to select which registry to push to, use the command below:
draft config set registry <your Docker hub or Azure Container Registry>
If you're using ACR, you can also log into your registry using the Azure CLI.
az acr login -n <your ACR instance name> -g <your ACR instance resource group>
Now you'll create the first two services, parrot and captainkube.
- The captainkube service, a simple Go app, is represented by Captain Kube from the Children's Illustrated Guide to Kubernetes. This service constantly watches the pods running in the Kubernetes cluster. Whenever a pod is activated, updated, or deleted from the cluster, captainkube tells the parrot service what just happened.
- The parrot service is essentially an ASP.NET Core app with a Web API back-end. The Web API bubbles events up to the HTML client via a SignalR Hub. Parrot essentially "parrots" what captainkube is telling him in the form of Semantic UI cards on the UI side. When services pop into the cluster, they're represented by characters shown in the cards.
These two baseline services need to be running first, so you can Draft them up into the cluster using the commands below.
cd parrot
draft up
cd ..
cd captainkube
draft up
cd ..
You'll be provided feedback as the deployment takes place.
Once the deployment has completed, enter this Kubernetes CLI command to see everything you've deployed into the cluster.
kubectl get svc,pod,ing --namespace phippyandfriends
You should see something like this in your terminal window.
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
parrot-parrot ClusterIP 10.0.224.230 <none> 80/TCP 3m
NAME READY STATUS RESTARTS AGE
captainkube-captainkube-f5b4487c5-shw4p 1/1 Running 0 3m
parrot-parrot-677cc74b47-zdw6z 1/1 Running 0 3m
NAME HOSTS ADDRESS PORTS
parrot-parrot parrot.0d7b3d707c094da087a7.westus.aksapp.io 80
It may take a few minutes for the ingress DNS to be matched up to the public IP address for the cluster. If you don't see an IP address listed for the parrot
service, just type this command and watch the terminal window update automatically until you have a public IP address for the ingress.
kubectl get ing --namespace phippyandfriends -w
Eventually, your ingress will reflect the public IP address, which is your sign that parrot's DNS will work. So copy it from the terminal window.
Drop parrot's ingress URI into a web browser and you'll see the dashboard, which confirms you've got two services - parrot and captainkube - running in your cluster.
The Phippy service is a super-simple PHP app.
Next, CD into the phippy directory, as we definitely want to make sure we deploy our star of the show, Phippy, into our AKS cluster. Use the same draft up
command as you did for parrot and captainkube, and you'll see the phippy service's deployment status as it occurs.
The moment the deployment finishes, the dashboard will light up with Phippy!
The final service is a basic Node.js application represented by the Node.js-decorated Azure Brady, the Open Cloud Ninja Sloth.
You can cd into this service's folder and deploy it using draft up
as you did with the others. But for fun, do this in a window that's side-by-side with the parrot dashboard. This way you can see services appear as you draft up
and vanish as you draft delete
.
Scale your nodebrady by running this:
kubectl scale deployment/nodebrady-nodebrady --replicas 3 --namespace phippyandfriends
Watch as more brady ninjas come to life!
You could also leverage Azure DevOps to implement a CI/CD pipeline for each app. For that you could create one Azure build pipeline per app by using the associated YAML definition: azure-build-pipeline.yml.
For more information, you could follow this tutorial: Using Azure DevOps to setup a CI/CD pipeline and deploy to Kubernetes.
Phippy and Friends is open-source, and we'd love your contributions. Submit issues, then work those issues and send us a pull request. Customize the parrot dashboard with a theme, put the characters on a boat, launch them into space. We'd love to see what other characters you'll add to the dashboard!
Sometimes a previous deployment would fail and you would receive a message like so:
error while releasing: could not upgrade release: rpc error: code = Unknown desc = "parrot" has no deployed releases
if that happens, you need to delete that failed deployment by running the following command, replacing parrot
with the failed deployment name:
helm delete --purge parrot
Some awesome people worked on the Phippy and Friends demo. Stella Lin brought the idea to Brady Gaster, who then got a ton of help from Ralph Squillace and Ahmed Sabbour to bring it to life and Mathieu Benoit for his Azure DevOps build pipeline. As mentioned earlier, Phippy and Friends was originally inspired by a blog post written by Matt Butcher. Phippy and friends were conceived by Matt Butcher, Karen Chu, and Bailey Beougher and are licensed by the CNCF under the CC-BY license. More info at phippy.io. Goldie the Gopher is based on the Go Gopher by Renee French.
You can help too, by submitting a pull request and adding your own contributions. When you do, make sure to add your contributions' summary to this section, too!