Improve clarity of k8s instructions for Windows

planetf1 commented 2 years ago

The instructions for setting up microk8s on windows at https://odpi.github.io/egeria-docs/guides/operations/kubernetes/k8s/ refer the user to the official windows instructions.

Whilst that's initially appropriate -- to download and run the GUI installer, it then needs to be more explicit.

Following install/reboot the same instructions are used as for macOS (so this can be common) ie

Microsoft Windows [Version 10.0.19044.1348]

nigel@MEGA C:\Users\nigel
$ microk8s start
Started.

nigel@MEGA C:\Users\nigel
$ microk8s status --wait-ready
microk8s is running
high-availability: no
  datastore master nodes: 127.0.0.1:19001
  datastore standby nodes: none
addons:
  enabled:
    ha-cluster           # Configure high availability on the current node
  disabled:
    ambassador           # Ambassador API Gateway and Ingress
    cilium               # SDN, fast with full network policy
    dashboard            # The Kubernetes dashboard
    dns                  # CoreDNS
    fluentd              # Elasticsearch-Fluentd-Kibana logging and monitoring
    gpu                  # Automatic enablement of Nvidia CUDA
    helm                 # Helm 2 - the package manager for Kubernetes
    helm3                # Helm 3 - Kubernetes package manager
    host-access          # Allow Pods connecting to Host services smoothly
    ingress              # Ingress controller for external access
    istio                # Core Istio service mesh services
    jaeger               # Kubernetes Jaeger operator with its simple config
    kata                 # Kata Containers is a secure runtime with lightweight VMS
    keda                 # Kubernetes-based Event Driven Autoscaling
    knative              # The Knative framework on Kubernetes.
    kubeflow             # Kubeflow for easy ML deployments
    linkerd              # Linkerd is a service mesh for Kubernetes and other frameworks
    metallb              # Loadbalancer for your Kubernetes cluster
    metrics-server       # K8s Metrics Server for API access to service metrics
    multus               # Multus CNI enables attaching multiple network interfaces to pods
    openebs              # OpenEBS is the open-source storage solution for Kubernetes
    openfaas             # openfaas serverless framework
    portainer            # Portainer UI for your Kubernetes cluster
    prometheus           # Prometheus operator for monitoring and logging
    rbac                 # Role-Based Access Control for authorisation
    registry             # Private image registry exposed on localhost:32000
    storage              # Storage class; allocates storage from host directory
    traefik              # traefik Ingress controller for external access

nigel@MEGA C:\Users\nigel
$ microk8s enable dns storage helm3
Enabling DNS
Applying manifest
serviceaccount/coredns created
configmap/coredns created
Warning: spec.template.metadata.annotations[scheduler.alpha.kubernetes.io/critical-pod]: non-functional in v1.16+; use the "priorityClassName" field instead
deployment.apps/coredns created
service/kube-dns created
clusterrole.rbac.authorization.k8s.io/coredns created
clusterrolebinding.rbac.authorization.k8s.io/coredns created
Restarting kubelet
DNS is enabled
Enabling default storage class
deployment.apps/hostpath-provisioner created
storageclass.storage.k8s.io/microk8s-hostpath created
serviceaccount/microk8s-hostpath created
clusterrole.rbac.authorization.k8s.io/microk8s-hostpath created
clusterrolebinding.rbac.authorization.k8s.io/microk8s-hostpath created
Storage will be available soon
Enabling Helm 3
Fetching helm version v3.5.0.
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 11.7M  100 11.7M    0     0  4935k      0  0:00:02  0:00:02 --:--:-- 4935k
Helm 3 is enabled

nigel@MEGA C:\Users\nigel
$ microk8s kubectl get all --all-namespaces
NAMESPACE     NAME                                           READY   STATUS    RESTARTS   AGE
kube-system   pod/calico-kube-controllers-578cfb99d5-zd9px   1/1     Running   0          5m17s
kube-system   pod/coredns-7f9c69c78c-2pqxx                   1/1     Running   0          29s
kube-system   pod/calico-node-cxpfc                          1/1     Running   0          5m17s

NAMESPACE     NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                  AGE
default       service/kubernetes   ClusterIP   10.152.183.1    <none>        443/TCP                  5m24s
kube-system   service/kube-dns     ClusterIP   10.152.183.10   <none>        53/UDP,53/TCP,9153/TCP   29s

NAMESPACE     NAME                         DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR            AGE
kube-system   daemonset.apps/calico-node   1         1         1       1            1           kubernetes.io/os=linux   5m24s

NAMESPACE     NAME                                      READY   UP-TO-DATE   AVAILABLE   AGE
kube-system   deployment.apps/calico-kube-controllers   1/1     1            1           5m24s
kube-system   deployment.apps/coredns                   0/1     1            0           29s
kube-system   deployment.apps/hostpath-provisioner      0/1     0            0           18s

NAMESPACE     NAME                                                 DESIRED   CURRENT   READY   AGE
kube-system   replicaset.apps/calico-kube-controllers-578cfb99d5   1         1         1       5m17s
kube-system   replicaset.apps/coredns-7f9c69c78c                   1         1         0       29s

nigel@MEGA C:\Users\nigel
$

A few other observations:

It's also worth adding a caveat to docker desktop & make it the last item in the list (including a possible note that the egeria team cannot help)
typo 'Furether information'
Moving the microk8s example to a separate page, and adding in rancher desktop on the summary may add clarity - distinguishing between the general principles & choice of runtimes vs one we picked to be very explicit about to help new starters in k8s
Under 'accessing applications' we could add an explicit example of accessing microk8s ports locally (just as we need in the dojo) - be it via port forwarwarding, nodeport etc. Where possible this should link into the microk8s docs

ON Helm....

A caveat is noted at https://odpi.github.io/egeria-docs/guides/operations/kubernetes/helm/ that the user needs to use 'microk8s.kubectl' or 'microk8s.helm'. This is non-standard. For the dojo we will explicitly use 'microk8s helm3 ....' but some users may still be confused by these joint instructions. An adominition, perhaps offering the variant may help as otherwise the user may pickup an old version or wrong version of helm, and for those new to k8s this could be confusing

And testing our charts - the instructions working ok on x86 windows 10


nigel@MEGA C:\Users\nigel
$ microk8s helm3 repo add egeria https://odpi.github.io/egeria-charts
WARNING: Kubernetes configuration file is group-readable. This is insecure. Location: /var/snap/microk8s/2551/credentials/client.config
"egeria" has been added to your repositories

nigel@MEGA C:\Users\nigel
$ microk8s helm3 search repo egeria
WARNING: Kubernetes configuration file is group-readable. This is insecure. Location: /var/snap/microk8s/2551/credentials/client.config
NAME                    CHART VERSION   APP VERSION     DESCRIPTION
egeria/egeria-base      3.3.0           3.3             Egeria simple deployment to Kubernetes
egeria/egeria-cts       3.3.0           3.3             Egeria Conformance Test Suite deployment to Kub...
egeria/egeria-pts       3.3.1           3.3             Egeria Performance Test Suite deployment to Kub...
egeria/odpi-egeria-lab  3.3.0           3.3             Egeria lab environment

nigel@MEGA C:\Users\nigel
$ microk8s helm3 install lab egeria/odpi-egeria-lab
WARNING: Kubernetes configuration file is group-readable. This is insecure. Location: /var/snap/microk8s/2551/credentials/client.config
NAME: lab
LAST DEPLOYED: Thu Nov 11 12:16:33 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
ODPi Egeria lab tutorial
---

The Egeria tutorials have now been deployed to Kubernetes.
It may take a minute or so for everything to start up.

Open your web browser and go to addressofmycluster:30888 to
get started

You may need to contact your cluster admin, or read your cloud provider helptext to understand
the correct 'addressofmycluster' to use.

If you experience problems, check memory consumption on your nodes. A minimum of
a 3 node cluster, 2GB per node; or a desktop environment with 6GB dedicated is recommended.

Please provide any feeback via a github issue at https://github.com/odpi/egeria or
join us on slack via https://http://slack.lfai.foundation

- The ODPi Egeria team

nigel@MEGA C:\Users\nigel
$

planetf1 commented 2 years ago

The 'insure' WARNING is from an out of the box install of microk8s ...

planetf1 commented 2 years ago

Rancher Desktop can also be added to the list for Windows users (perhaps mac too)

Install from https://rancherdesktop.io/

This also has explicit WSL integration, so may be a simpler/easier fit for hybrid work, ie when developing a connector under WSL2 & running it alongside Egeria running under k8s

Rancher desktop adds 'kubectl' and 'helm' to the standard path during install

As such the usual commands used for linux/macos works just fine

Overall rancher desktop is more complete, more integrated, has GUI, supports pod metrics (top pods/nodes for example) However on the downside the default config took 12GB on my 16GB machine -- and we may have users with 8GB machines running dojo/demos. Need to understand if configurable It also seems to run with a higher background level of CPU vs microk8s. It seems to run everything under WSL- beyond the GUI (whilst microk8s uses a slightly more conventional VM setup) So whilst overall it may be better, there is some risk in going down this route for Dojo However for egeria, it works....

planetf1 commented 2 years ago

these docs were updated (simply point to the official docs) for the dojo. closing.

odpi / egeria-docs

Improve clarity of k8s instructions for Windows #163