Merge pull request #70 from seifrajhi/kube-developper-workshop

feat: 	kube-developper-workshop

kube-developper-workshop/.devcontainer/devcontainer.json

@@ -0,0 +1,29 @@
+{
+  "image": "ubuntu:latest",
+  "features": {
+    "kubectl-helm-minikube": {
+      "version": "latest",
+      "helm": "latest",
+      "minikube": "none"
+    },
+    "common": {
+      "username": "vscode",
+      "uid": "1000",
+      "gid": "1000",
+      "installZsh": true,
+      "installOhMyZsh": true
+    },
+    "azure-cli": "latest",
+    "ghcr.io/eliises/devcontainer-features/bash-profile": {
+      "command": "source <(kubectl completion bash); alias k=kubectl; complete -o default -F __start_kubectl k; alias kubens='kubectl config set-context --current --namespace ';",
+      "file": "/etc/bash.bashrc"
+    }
+  },
+  "remoteUser": "vscode",
+  "extensions": [
+    "yzhang.markdown-all-in-one",
+    "DavidAnson.vscode-markdownlint",
+    "streetsidesoftware.code-spell-checker",
+    "ms-kubernetes-tools.vscode-kubernetes-tools"
+  ]
+}

kube-developper-workshop/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+  "[markdown]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "yaml.schemas": {
+    "https://json.schemastore.org/github-workflow.json": "file:///home/ben/dev/kube-workshop/.github/workflows/build.yaml"
+  }
+}

kube-developper-workshop/00-pre-reqs/readme.md

@@ -0,0 +1,163 @@
+# ⚒️ Workshop Pre Requisites
+
+As this is a completely hands on workshop, you will need several things before you can start:
+
+- Access to an Azure Subscription where you can create resources.
+- bash or a bash compatible shell (e.g. zsh), please do not attempt to use PowerShell or cmd.
+- A good editor, and [VS Code](https://code.visualstudio.com/) is strongly recommended
+  - [Kubernetes extension](https://marketplace.visualstudio.com/items?itemName=ms-kubernetes-tools.vscode-kubernetes-tools) also highly recommended.
+- [Azure CLI](https://aka.ms/azure-cli)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
+- [helm](https://helm.sh/docs/intro/install/)
+
+## Install dependencies
+
+The above listed tools are already set up in `.devcontainer` folder located in the git repository of this workshop: <https://github.com/benc-uk/kube-workshop>.
+If you've never used Dev Containers, check out [developing inside a Container using Visual Studio Code Remote Development](https://code.visualstudio.com/docs/devcontainers/containers).
+
+### Install dependencies manually
+
+Alteratively you can can install the dependencies yourself by following the steps below.
+
+#### 🌩️ Install Azure CLI
+
+To set-up the Azure CLI on your system, install it in one of the below ways.
+
+On Ubuntu/Debian Linux, requires sudo:
+
+```bash
+curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
+```
+
+On MacOS, use homebrew:
+
+```bash
+brew update && brew install azure-cli
+```
+
+If the commands above don't work, please refer to: [https://aka.ms/azure-cli](https://aka.ms/azure-cli)
+
+#### ⛑️ Install Helm & Kubectl
+
+<details markdown="1">
+<summary>Install Helm & Kubectl - Linux (Ubuntu/Debian)</summary>
+
+Two ways are provided for each tool, one without needing sudo, the other requires sudo, take your pick but don't run both!
+
+By default the 'no sudo' commands for helm & kubectl install binaries into `~/.local/bin` so if this isn't in your PATH you can copy or move the binary elsewhere, or simply run `export PATH="$PATH:$HOME/.local/bin"`
+
+```bash
+# Install kubectl - no sudo
+curl -s https://raw.githubusercontent.com/benc-uk/tools-install/master/kubectl.sh | bash
+
+# Install kubectl - with sudo
+curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+chmod +x ./kubectl
+sudo mv ./kubectl /usr/bin/kubectl
+
+# Install helm - no sudo
+curl -s https://raw.githubusercontent.com/benc-uk/tools-install/master/helm.sh | bash
+
+# Install helm - with sudo
+curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+```
+
+</details>
+
+<details markdown="1">
+<summary>Install Helm & Kubectl - MacOS</summary>
+
+```bash
+# Install kubectl - with sudo
+curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
+chmod +x ./kubectl
+sudo mv ./kubectl /usr/local/bin/kubectl
+
+# Install Helm
+curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+```
+
+</details>
+
+#### ⚙️ Set up bash profile
+
+Set up the user bash profile for K8s to make it easier to run all the commands
+
+```sh
+echo "source <(kubectl completion bash)" >> ~/.bashrc
+echo "alias k=kubectl" >> ~/.bashrc
+echo "complete -o default -F __start_kubectl k" >> ~/.bashrc
+echo "export PATH=$PATH:/home/azureuser/.local/bin" >> ~/.bashrc
+```
+
+To have `.bashrc` changes take affect in your current terminal, you must reload `.bashrc` with:
+
+```sh
+. ~/.bashrc
+```
+
+## ✅ Verify installation
+
+Double check that everything in installed and working correctly with:
+
+```sh
+# Try commands with tab completion
+k get pods -A
+helm
+az
+```
+
+## 🔐 Login to Azure
+
+The rest of this workshop assumes you have access to an Azure subscription, and have the Azure CLI
+working & signed into the tenant & subscription you will be using. Some Azure CLI commands to help you:
+
+- `az login` or `az login --tenant {TENANT_ID}` - Login to the Azure CLI, use the `--tenant` switch
+  if you have multiple accounts.
+- `az account set --subscription {SUBSCRIPTION_ID}` - Set the subscription the Azure CLI will use.
+- `az account show -o table` - Show the subscription the CLI is configured to use.
+
+## 😢 Stuck?
+
+Getting all the tools set up locally is the highly recommended path to take, if you are stuck there
+are some other options to explore, but these haven't been tested:
+
+- Use the [Azure Cloud Shell](https://shell.azure.com/bash) which has all of these tools except VS Code,
+  a simple web code editor is available. However if you download the
+  [VS Code server](https://aka.ms/install-vscode-server/setup.sh), then run that from inside Cloud Shell
+  you can get access to the full web based version of VS Code.
+- Go to the [repo for this workshop on GitHub](https://github.com/benc-uk/kube-workshop/codespaces)
+  and start a new Codespace from it, you should get a terminal you can use and have all the tools available.
+  Only available if you have access to GitHub Codespaces.
+
+## 💲 Variables File
+
+Although not essential, it's advised to create a `vars.sh` file holding all the parameters that will
+be common across many of the commands that will be run. This way you have a single point of reference
+for them and they can be easily reset in the event of a session timing out or terminal closing.
+
+Sample `vars.sh` file is shown below, feel free to use any values you wish for the resource group, region cluster name etc.
+
+> Note: The ACR name must be globally unique and cannot contain hyphens, dots, or underscores.
+
+```bash
+RES_GROUP="kube-workshop"
+REGION="westeurope"
+AKS_NAME="__change_me__"
+ACR_NAME="__change_me__"
+KUBE_VERSION="1.27.1"
+```
+
+> Note: New versions of Kubernetes are released all the time, and eventually older versions are removed from Azure. Rather than constantly update this guide the following command can be used to get the latest version: `az aks get-versions --location "westeurope" -o tsv --query "orchestrators[-1].orchestratorVersion"`
+
+To use the file simply source it through bash with the below command, do this before moving to the next stage.
+
+```sh
+source vars.sh
+```
+
+It's worth creating a project folder locally (or even a git repo) at this point, in order to keep your work in, you haven't done so already. We'll be creating & editing files later
+
+## Navigation
+
+[Return to Main Index 🏠](../readme.md) ‖ [Next Section ⏩](../01-cluster/readme.md)

kube-developper-workshop/00-pre-reqs/vars.sh.sample

@@ -0,0 +1,5 @@
+RES_GROUP="kube-workshop"
+REGION="westeurope"
+AKS_NAME="__change_me__"
+ACR_NAME="__change_me__"
+KUBE_VERSION="1.25.5"

kube-developper-workshop/01-cluster/readme.md

@@ -0,0 +1,88 @@
+# 🚦 Deploying Kubernetes
+
+Deploying AKS and Kubernetes can be extremely complex, with many networking, compute and other aspects to consider.
+However for the purposes of this workshop, a default and basic cluster can be deployed very quickly.
+
+## 🚀 AKS Cluster Deployment
+
+The following commands can be used to quickly deploy an AKS cluster:
+
+```bash
+# Create Azure resource group
+az group create --name $RES_GROUP --location $REGION
+
+# Create cluster
+az aks create --resource-group $RES_GROUP \
+  --name $AKS_NAME \
+  --location $REGION \
+  --node-count 2 --node-vm-size Standard_B2ms \
+  --kubernetes-version $KUBE_VERSION \
+  --verbose \
+  --no-ssh-key
+```
+
+In case you get an error when creating cluster, `Version x.xx.x is not supported in this region.`, run the following to get the supported kubernetes version
+
+```sh
+az aks get-versions --location $REGION -o table
+```
+
+And re-run the create cluster command with supported version number.
+
+This should take around 5 minutes to complete, and creates a new AKS cluster with the following
+characteristics:
+
+- Two small B-Series _Nodes_ in a single node pool. _Nodes_ are what your workloads will be running on.
+- Basic 'Kubenet' networking, which creates an Azure network and subnet etc for us. [See docs if you wish to learn more about this topic](https://docs.microsoft.com/azure/aks/operator-best-practices-network)
+- Local cluster admin account, with RBAC enabled, this means we don't need to worry about setting up users or assigning roles etc.
+- AKS provide a wide range of 'turn key' addons, e.g. monitoring, AAD integration, auto-scaling, GitOps etc, however we'll not require for any of these to be enabled.
+- The use of SSH keys is skipped with `--no-ssh-key` as they won't be needed.
+
+The `az aks create` command has [MANY options](https://docs.microsoft.com/en-us/cli/azure/aks?view=azure-cli-latest#az-aks-create)
+however you shouldn't need to change or add any options, with some small exceptions:
+
+- You may wish to change the size or number of nodes, however this clearly has cost implications.
+
+## 🔌 Connect to the Cluster
+
+To enable `kubectl` (and other tools) to access the cluster, run the following:
+
+```bash
+az aks get-credentials --name $AKS_NAME --resource-group $RES_GROUP
+```
+
+This will create Kubernetes config file in your home directory `~/.kube/config` which is the default location, used by `kubectl`.
+
+Now you can run some simple `kubectl` commands to validate the health and status of your cluster:
+
+```bash
+# Get all nodes in the cluster
+kubectl get nodes
+
+# Get all pods in the cluster
+kubectl get pods --all-namespaces
+```
+
+Don't be alarmed by all the pods you see running in the 'kube-system' namespace. These are deployed by default by AKS and perform management & system tasks we don't need to worry about.
+You can still consider your cluster "empty" at this stage.
+
+## ⏯️ Appendix - Stopping & Starting the Cluster
+
+If you are concerned about the costs for running the cluster you can stop and start it at any time.
+This essentially stops the node VMs in Azure, meaning the costs for the cluster are greatly reduced.
+
+```bash
+# Stop the cluster
+az aks stop --resource-group $RES_GROUP --name $AKS_NAME
+
+# Start the cluster
+az aks start --resource-group $RES_GROUP --name $AKS_NAME
+```
+
+> 📝 NOTE: Start and stop operations do take several minutes to complete, so typically you would
+> perform them only at the start or end of the day.
+
+## Navigation
+
+[Return to Main Index 🏠](../readme.md) ‖
+[Previous Section ⏪](../00-pre-reqs/readme.md) ‖ [Next Section ⏩](../02-container-registry/readme.md)

kube-developper-workshop/02-container-registry/readme.md

@@ -0,0 +1,91 @@
+# 📦 Container Registry & Images
+
+We will deploy & use a private registry to hold the application container images. This is not strictly
+necessary as we could pull the images directly from the public, however using a private registry is
+a more realistic approach.
+
+[Azure Container Registry](https://docs.microsoft.com/azure/container-registry/) is what we will be
+using.
+
+## 🚀 ACR Deployment
+
+Deploying a new ACR is very simple:
+
+```bash
+az acr create --name $ACR_NAME --resource-group $RES_GROUP \
+--sku Standard \
+--admin-enabled true
+```
+
+> 📝 NOTE: When you pick a name for the resource with $ACR_NAME, this has to be **globally unique**, and not contain any underscores, dots or hyphens.
+> Name must also be in lowercase.
+
+## 📥 Importing Images
+
+For the sake of speed and maintaining the focus on Kubernetes we will import pre-built images from another public registry (GitHub Container Registry), rather than build them from source.
+
+We will cover what the application does and what these containers are for in the next section, for
+now we can just import them.
+
+To do so we use the `az acr import` command:
+
+```bash
+# Import application frontend container image
+az acr import --name $ACR_NAME --resource-group $RES_GROUP \
+--source ghcr.io/benc-uk/smilr/frontend:stable \
+--image smilr/frontend:stable
+
+# Import application data API container image
+az acr import --name $ACR_NAME --resource-group $RES_GROUP \
+--source ghcr.io/benc-uk/smilr/data-api:stable \
+--image smilr/data-api:stable
+```
+
+If you wish to check and see imported images, you can go over to the ACR resource in the Azure portal, and into the 'Repositories' section.
+
+> 📝 NOTE: we are not using the tag `latest` which is a common mistake when working with Kubernetes
+> and containers in general.
+
+## 🔌 Connect AKS to ACR - as Azure Subscription Owner
+
+Kuberenetes requires a way to authenticate and access images stored in private registries.
+There are a number of ways to enable Kubernetes to pull images from a private registry, however AKS provides a simple way to configure this through the Azure CLI.
+The downside is this requires you to have 'Owner' permission within the subscription, in order to assign the role.
+
+```bash
+az aks update --name $AKS_NAME --resource-group $RES_GROUP --attach-acr $ACR_NAME
+```
+
+If you are curious what this command does, it essentially is just assigning the "ACR Pull" role in Azure IAM to the managed identity used by AKS, on the ACR resource.
+
+If you see the following error `Could not create a role assignment for ACR. Are you an Owner on this subscription?`, you will need to proceed to the alternative approach below.
+
+## 🔌 Connect AKS to ACR - Alternative
+
+If you do not have Azure Owner permissions, you will need to fall back to an alternative approach.
+This involves two things:
+
+- Adding an _Secret_ to the cluster containing the credentials to pull images from the ACR.
+- Including a reference to this _Secret_ in every _Deployment_ you create or update the _ServiceAccount_
+  used by the _Pods_ to reference this _Secret_.
+
+Run these commands to create the _Secret_ with the ACR credentials, and patch the default _ServiceAccount_:
+
+```bash
+kubectl create secret docker-registry acr-creds \
+  --docker-server=$ACR_NAME.azurecr.io \
+  --docker-username=$ACR_NAME \
+  --docker-password=$(az acr credential show --name $ACR_NAME --query "passwords[0].value" -o tsv)
+
+kubectl patch serviceaccount default --patch '"imagePullSecrets": [{"name": "acr-creds" }]'
+```
+
+> 💥 IMPORTANT! Do NOT follow this approach of patching the default _ServiceAccount_ in production or a cluster running real workloads, treat this as a simplifying workaround.
+
+These two commands introduce a lot of new Kubernetes concepts in one go! Don't worry about them for
+now, some of this such as _Secrets_ we'll go into later. If the command is successful, move on.
+
+## Navigation
+
+[Return to Main Index 🏠](../readme.md) ‖
+[Previous Section ⏪](../01-cluster/readme.md) ‖ [Next Section ⏩](../03-the-application/readme.md)