microsoft/aksworkshop

Azure Kubernetes Service (AKS) workshop website content

PLEASE NOTE: CONTENT MIGRATED

Please note that AKS workshop is now hosted on Microsoft Learn. You may continue to fork this repository, but future updates will be done on the Microsoft Learn platform. To access the new location, please use the following link: https://aka.ms/learn/aksworkshop

Technology

• The website is statically built using Jekyll and you'll find the different pages inside the _entries folder
• You can preview your edits locally if you run make build-run inside the repository root
• The build pipeline builds Docker images of the site and hosts it on a private repository on Azure Container Registry (msworkshops.azurecr.io)
• The master branch gets deployed to the production slot aksworkshop.io
• The staging branch gets deployed to the staging slot staging.aksworkshop.io
• The devsecops branch gets deployed to the devsecops slot devsecops.aksworkshop.io
• The kubesec branch gets deployed to the kubesec slot kubesec.aksworkshop.io

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

Since the workshop is running live, please fork and branch off staging, then submit a Pull Request against staging. After your PR is approved and staging is tested it will be merged to master on the next weekend. If it's urgent, then follow with a PR against master. In both cases it's desirable that every PR has an issue linking to it.

If you want your name to show up in the contributors, please add your GitHub username to _entries/99 Contributors.md in alphabetical order.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Legal Notices

Microsoft and any contributors grant you a license to the Microsoft documentation and other content in this repository under the Creative Commons Attribution 4.0 International Public License, see the LICENSE file, and grant you a license to any code in the repository under the MIT License, see the LICENSE-CODE file.

Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.

Privacy information can be found at https://privacy.microsoft.com/en-us/

Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents, or trademarks, whether by implication, estoppel or otherwise.

aksworkshop's Issues

Wrong tab name in Monitoring lab description

In paragraph "2.6 Monitoring" the description references a tab with the name "Containers", but in the picture that follows the description, the "Controllers" tab is selected. The picture displays the right selection. Correct the description to align with the text.

site doesn't build locally

I forked this repo with the intention of adding some content. I'm trying to build/run locally and the site doesn't seem to build

make build-run
docker build -t azch/aks-site:latest -f Dockerfile .
Sending build context to Docker daemon  56.34MB
Step 1/8 : FROM jekyll/builder AS build
 ---> 4605d94a6b36
Step 2/8 : WORKDIR /src/app
 ---> Using cache
 ---> 68e9fbcc3244
Step 3/8 : COPY . .
 ---> Using cache
 ---> b98c900dfb3e
Step 4/8 : RUN mkdir _site && mkdir .jekyll-cache &&     jekyll build --future
 ---> Running in 71d41bca2804
ruby 2.6.5p114 (2019-10-01 revision 67812) [x86_64-linux-musl]
Configuration file: /src/app/_config.yml
                    ------------------------------------------------
      Jekyll 4.0.0   Please append `--trace` to the `build` command
                     for any additional information or backtrace.
                    ------------------------------------------------
The command '/bin/sh -c mkdir _site && mkdir .jekyll-cache &&     jekyll build --future' returned a non-zero code: 1
make: *** [build-run] Error 1

istio logs a are not showing in Azure monitor.

I have followed below steps.
https://github.com/microsoft/aksworkshop/blob/master/_entries/02-06%20challenge3.md

When I Query , I am able to see data

InsightsMetrics | where Name == "jaeger_collector_spans_received_total" | where Namespace =="prometheus" | project Name, Val, Tags , Namespace, TimeGenerated , Computer

When I query(Istio), not able to see data.

InsightsMetrics | where Name contains "istio" | where Namespace =="prometheus" | project Name, Val, Tags , Namespace, TimeGenerated

Why my istio logs are not forwarding to Azure monitor

Add Service Mesh Section

Add service mesh with Linkerd, as the first solution, as it the easiest to get started with. Others could be added later.

Add Cost Management Section

Add cost management section to the workshop.

Current plan is to use https://kubecost.com

No way to enable cross-scripting in browser

in https://aksworkshop.io/#frontend it is mentionned :

Browse to the public hostname of the frontend and watch as the number of orders change
Once the Ingress is deployed, you should be able to access the frontend at http://frontend.[cluster_specific_dns_zone], for example http://frontend.52.255.217.198.nip.io
If it doesn’t work from the first trial, give it a few more minutes or try a different browser.

Note: you might need to enable cross-scripting in your browser; click on the shield icon on the address bar (for Chrome) and allow unsafe script to be executed.

But there is no more options in Edge, IE11 neither : https://blogs.windows.com/windowsexperience/2018/07/25/announcing-windows-10-insider-preview-build-17723-and-build-18204/

In Firefox neither :
https://support.mozilla.org/en-US/kb/disable-third-party-cookies
https://support.mozilla.org/en-US/kb/mixed-content-blocking-firefox#firefox:win10:fx70

I tried F12 in Edge :
SEC7120: [CORS] Le « ms-appx-web://microsoft.microsoftedge » d'origine n'a pas pu autoriser une ressource cross-origin font à « ms-appx-web:///assets/Fonts/BrowserMDL.ttf#Browser MDL2 Assets ».

or Dev bar in Firefox, no magic option to enable it :
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://captureorder.52.149.107.21.nip.io/v1/order?timestamp=1574095997293. (Reason: CORS disabled).

Installing nginx-ingress helm chart fails

The step for installing the ingress asks me to use

helm repo add stable https://kubernetes-charts.storage.googleapis.com/

and then install the helm chart using

helm install nginx-ingress stable/nginx-ingress \
    --namespace ingress \
    --set controller.replicaCount=2 \
    --set controller.nodeSelector."beta\.kubernetes\.io/os"=linux \
    --set defaultBackend.nodeSelector."beta\.kubernetes\.io/os"=linux

It looks like that repo has been deprecated because the helm install fails with

Error: failed to download "stable/nginx-ingress" (hint: running `helm repo update` may help)

Following guidance here got me going again https://stackoverflow.com/a/57970816. Note that the chart is considered deprecated in the new repo. It recommends using https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx instead.

Github Actions

@jschluchter assigned

AKS

2.2 Deploy MongoDB fails with doing helm init

1. I applied helm-rbac.yml
2. MISTAKE: just called helm init, should have called "helm init --service-account tiller"
3. FAILS: helm install stable/mongodb ....
4. tried to call: helm init --service-account tiller
5. STILL FAILS: helm install stable/mongodb ....

SOLUTION: thank goodness this was early in the workshop
Created a new cluster and called;

helm init --service-account tiller
SUCCESS: helm install stable/mongodb ....

So is there a way to correct the helm init in the failing case?

Max retries exceeded aks_virtual_node-0.2.0-py2.py3-none-any.whl

This step fails:

$ az extension add --source https://aksvnodeextension.blob.core.windows.net/aks-virtual-node/aks_virtual_node-0.2.0-py2.py3-none-any.whl
Are you sure you want to install this extension? (y/n): y
Please ensure you have network connection. Error detail: HTTPSConnectionPool(host='aksvnodeextension.blob.core.windows.net', port=443): Max retries exceeded with url: /aks-virtual-node/aks_virtual_node-0.2.0-py2.py3-none-any.whl (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7f0799f6a7b8>: Failed to establish a new connection: [Errno -2] Name or service not known',))

AKS Deployments fails on an Azure Pass without registering the network provider

Folks running the workshop on an Azure Pass, need to run this command via the Azure Shell else the AKS deployment will fail.

$ az provider register -n Microsoft.Network

Azure Cloud Shell has Helm 3 - The lab doesn't support it yet

As Azure Cloud Shell now comes with Helm 3, a lab participant cannot easily use this lab anymore. At least, the solutions are not valid for Helm 3. The main issues reside in the MongoDb install, Nginx-ingress install and the Cert-Manager install.

Task 2.5 enabling TLS/SSL breaks frontend due to how the env var is used

2.5 doesn't currently seem 100% achievable due to the code of the frontend having http:// hard coded into it.

I notice there's a open PR on the frontend to fix this Azure/azch-frontend#1 but that's been open a while.

Is there something I've missed here?

Update instructions to use new AKS + ACR attachment

Update the ACR authentication instructions to use this https://docs.microsoft.com/en-us/azure/aks/cluster-container-registry-integration

too many certificates already issued for: nip.io: see https://letsencrypt.org/docs/rate-limits/

I am walk through the workshop and got the following error configuring the certificate.

Here is the description of my frontend certificate.

How do i resolve this issue?

Name: frontend-tls-secret
Namespace: default
Labels:
Annotations:
API Version: certmanager.k8s.io/v1alpha1
Kind: Certificate
Metadata:
Creation Timestamp: 2019-10-17T02:11:34Z
Generation: 2
Owner References:
API Version: extensions/v1beta1
Block Owner Deletion: true
Controller: true
Kind: Ingress
Name: frontend
UID: c4d69bac-f5c0-4fbc-99e3-1cc7be0efd47
Resource Version: 9060
Self Link: /apis/certmanager.k8s.io/v1alpha1/namespaces/default/certificates/frontend-tls-secret
UID: 44dcc8b3-a923-4df7-a18f-34a61a906b1f
Spec:
Acme:
Config:
Domains:
frontend.13.66.86.47.nip.io
http01:
Ingress:
Dns Names:
frontend.13.66.86.47.nip.io
Issuer Ref:
Kind: ClusterIssuer
Name: letsencrypt
Secret Name: frontend-tls-secret
Status:
Acme:
Order:
URL:
Conditions:
Last Transition Time: 2019-10-17T02:11:36Z
Message: Failed to create new order: acme: urn:ietf:params:acme:error:rateLimited: Error creating new order :: too many certificates already issued for: nip.io: see https://letsencrypt.org/docs/rate-limits/
Reason: ValidateError
Status: False
Type: Ready
Events:
Type Reason Age From Message

---

Warning ErrCreateOrder 11s (x33 over 30m) cert-manager Error creating order: acme: urn:ietf:params:acme:error:rateLimited: Error creating new order :: too many certificates already issued for: nip.io: see https://letsencrypt.org/docs/rate-limits/

helm install: unknown flag --name

In unit 7, Deploy a Kubernetes ingress controller using NGINX, step 2, this command fails:
helm install --name nginx-ingress stable/nginx-ingress
--namespace ingress
--set controller.replicaCount=2
--set controller.nodeSelector."beta.kubernetes.io/os"=linux
--set defaultBackend.nodeSelector."beta.kubernetes.io/os"=Linux

The error: Error: unknown flag: --name

I have this helm version in the cloud shell (shown with helm version):
3.2.0

The documentation shows to supply the name without the --name flag, and this succeeds:

helm install nginx-ingress stable/nginx-ingress
--namespace ingress
--set controller.replicaCount=2
--set controller.nodeSelector."beta.kubernetes.io/os"=linux
--set defaultBackend.nodeSelector."beta.kubernetes.io/os"=Linux

Add security section

Add Security section.

Current plan based from https://aka.ms/aks/secure

replace basic LB with SLB

We had too many errors in the provided environment with Load Balancer - replace instructions for provisioning cluster to use "standard" instead of "basic" LB

Loadbalancer needs to be explicitly defined as "basic"

When using Azure Pass, users are not allowed to create a standard load balancer, but since standard is now the default (when creating the cluster with az aks create) you need to use the flag --load-balancer-sku and set it to basic.

Suggested change:

Change this

  az aks create --resource-group <resource-group> \
    --name <unique-aks-cluster-name> \
    --location <region> \
    --kubernetes-version $version \
    --generate-ssh-keys

To this

  az aks create --resource-group <resource-group> \
    --name <unique-aks-cluster-name> \
    --location <region> \
    --kubernetes-version $version \
    --generate-ssh-keys \´
    --load-balancer-sku basic 

Service Mesh Lab

Logs for autoscaler

In "Scaling" section add detail on how to get Autoscaler logs
https://docs.microsoft.com/en-us/azure/aks/cluster-autoscaler#retrieve-cluster-autoscaler-logs-and-status

Unable to run build, mkdir permission denied

Running make build-run results in an error on line 11 of the Dockerfile (where jekyll build is run), adding --trace gives more details, which is a permission error on the mkdir step

This is using Docker running inside WSL2

docker build -t azch/aks-site:latest -f Dockerfile .
Sending build context to Docker daemon  49.91MB
Step 1/8 : FROM jekyll/builder AS build
 ---> 40cf7a7e8f7e
Step 2/8 : WORKDIR /src/app
 ---> Using cache
 ---> 67ac0a23d069
Step 3/8 : COPY . .
 ---> Using cache
 ---> f920d20498cb
Step 4/8 : RUN mkdir _site &&     jekyll build --future --trace
 ---> Running in 4a8b5106a410
ruby 2.6.4p104 (2019-08-28 revision 67798) [x86_64-linux-musl]
Configuration file: /src/app/_config.yml
/usr/local/lib/ruby/2.6.0/fileutils.rb:239:in `mkdir': Permission denied @ dir_s_mkdir - /src/app/.jekyll-cache (Errno::EACCES)
        from /usr/local/lib/ruby/2.6.0/fileutils.rb:239:in `fu_mkdir'
        from /usr/local/lib/ruby/2.6.0/fileutils.rb:217:in `block (2 levels) in mkdir_p'
        from /usr/local/lib/ruby/2.6.0/fileutils.rb:215:in `reverse_each'
        from /usr/local/lib/ruby/2.6.0/fileutils.rb:215:in `block in mkdir_p'
        from /usr/local/lib/ruby/2.6.0/fileutils.rb:200:in `each'
        from /usr/local/lib/ruby/2.6.0/fileutils.rb:200:in `mkdir_p'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/cache.rb:184:in `dump'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/cache.rb:101:in `[]='
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/cache.rb:45:in `clear_if_config_changed'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/site.rb:113:in `reset'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/site.rb:33:in `initialize'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/commands/build.rb:30:in `new'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/commands/build.rb:30:in `process'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/command.rb:89:in `block in process_with_graceful_fail'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/command.rb:89:in `each'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/command.rb:89:in `process_with_graceful_fail'
        from /usr/gem/gems/jekyll-4.0.0/lib/jekyll/commands/build.rb:18:in `block (2 levels) in init_with_program'
        from /usr/gem/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `block in execute'
        from /usr/gem/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `each'
        from /usr/gem/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `execute'
        from /usr/gem/gems/mercenary-0.3.6/lib/mercenary/program.rb:42:in `go'
        from /usr/gem/gems/mercenary-0.3.6/lib/mercenary.rb:19:in `program'
        from /usr/gem/gems/jekyll-4.0.0/exe/jekyll:15:in `<top (required)>'
        from /usr/gem/bin/jekyll:23:in `load'
        from /usr/gem/bin/jekyll:23:in `<main>'
The command '/bin/sh -c mkdir _site &&     jekyll build --future --trace' returned a non-zero code: 1
Makefile:17: recipe for target 'build-run' failed
make: *** [build-run] Error 1

Add Blue/Green deployment

There were many questions on deployment rollout strategies and how to implement simple blue/green.
May be worth to add small section on that

CosmosDB with MongoDB API

I think it would be a good idea to add a task (4.4) to replace MongoDB with CosmosDB and the MongoDB API.

Just a change with the connection information should be required to see the features of this PaaS service.

1.4 Tasks - Advanced cluster tasks - change Terraform to Azure Key Vault

mentions a) virtual nodes, b) enable MongoDB replication, and c) Terraform
however, the advanced tasks offer
a) virtual nodes, b) MongoDB replication, c) Azure Key Vault for secrets

-> please change the intro text in 1.4 from Terraform to Azure Key Vault

Azure Key Vault Steps Missing Secret Value for MongoUser

The yaml file captureorder-deployment-flexvol is missing the entry for MONGOUSER environment variable.

The steps in the documentation have it correctly though. Only the YAML file is missing the environment variable.
cc @sabbour

Certmanager version is too old

The version of certmanager that is used in the instructions (--version v0.5.2) is no longer supported. The oldest version allowed is 0.8.0

The instructions should be updated to use this new version, and to use the correct repository (stable/certmanager is not updated).

Suggested modification:

Change this:

helm install stable/cert-manager --name cert-manager --set ingressShim.defaultIssuerName=letsencrypt --set ingressShim.defaultIssuerKind=ClusterIssuer --version v0.5.2

To this:

# Install the CustomResourceDefinition resources separately
kubectl apply --validate=false -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.11/deploy/manifests/00-crds.yaml

# Create the namespace for cert-manager 
kubectl create namespace cert-manager

# Add the Jetstack Helm repository
helm repo add jetstack https://charts.jetstack.io

# Update your local Helm chart repository cache
helm repo update

# Install the cert-manager Helm chart
helm install \
  --name cert-manager \
  --namespace cert-manager \
  --version v0.11.0 \
  jetstack/cert-manager

Also, the yaml definitions for the ingress controllers needs to be updated to reflect the new certmanager domain.

Change this

annotations:
    certmanager.k8s.io/cluster-issuer: letsencrypt

To

annotations:
    cert-manager.io/cluster-issuer: letsencrypt

Azure Dev Spaces integration