This onboarding guide provides information about Kubernetes. Depending on your role or task you may find that your need for Kubernetes will fluctuate.
The official Kubernetes documentation is quite helpful; however, it can be overwhelming. We recommend glancing through the Concepts and Tasks sections. Furthermore, some useful sub-sections are:
Docker Desktop includes the ability to start a single-node Kubernetes cluster and provides the kubectl client. (The provided kubectl can also be used with other Kubernetes clusters.) This Docker Desktop deployment gives you an isolated sandbox to try out Kubernetes concepts and test most aspects of deployments, so it is highly recommended as a first step before interacting with other clusters.
Docker Desktop's Kubernetes includes some convenient features, such as
A default storage class provided for persistent volume claims. In persistent volume declarations, just leave off the storageClass attribute to use the default.
Services with type=LoadBalancer setup a host port mapping like -p with docker run
The status icon menu includes a "Kubernetes" sub-menu to switch contexts
The following screenshot shows how Kubernetes can be enabled from the Docker preferences:
In the Kubernetes section (1), set "Enable Kubernetes" (2)
Look for a green, "Kubernetes running" indicator (3), which is also in the status icon menu
If you are using an Ubuntu workstation, then MicroK8s is recommended as a similar solution.
Managed Kubernetes in GCP
Similar to other managed Kubernetes types, GKE takes care of mapping Kubernetes concepts to native Google Cloud constructs. Separate GKE clusters have been configured for development, staging, and production deployments.
The following diagram conveys general GKE concepts with annotations highlighting how these correspond to usage in Salus:
Kubernetes client config
kubectl is the command-line client that you run on your workstation to interact with Kubernetes clusters. If you don't already have kubectl, such as the one provided by Docker Desktop, you can use this documentation to install kubectl.
WARNINGkubectl makes it surprisingly easy to access both a local Docker Desktop cluster and any number of remote clusters in GKE. Please double check your current context using kubectl config current-context before executing deployment-altering commands.
To connect kubectl to an existing GKE cluster, you will first need to install the gcloud tool. After installation, you may need to run gcloud init to perform initial authentication.
With gcloud installed, it is recommended to use the Google Cloud web UI momentarily to locate the gcloud command to use for accessing an existing cluster.
Access the Kubernetes clusters as shown here:
Locate the desired cluster and click the "Connect" button shown here:
From the pop-up window, click on the copy icon to grab the gcloud command to use:
Run the copied command on your workstation to configure a new "kubeconfig" context for that cluster. The default context name is fairly long and ugly, so you can always rename it using kubectl config rename-context.
The Google Cloud web UI is also quite powerful. It includes the ability to inspect deployments, view logs, scale replicas, and much more. Give it a try since you might find some tasks are easier in the web UI rather than with kubectl.
Common tasks
In general, the official kubectl cheatsheet is a great resource to keep handy; however, the following describes a few specific tasks that we have needed.
kubectl is fairly self-documenting with the option to add -h at any level. The documentation of sub-commands even includes a few examples.
To get the current list of pods:
kubectl get pod
To watch the state of pods, such as after scaling or restart, add -w:
kubectl get pod -w
To view and follow the logs of a pod's container:
kubectl logs -f POD_NAME
If a pod has been running for a while, you can start the logs from a relative time offset by adding --since=DURATION, such as --since=1m. If the pod has more than one container, then you will need to add -c CONTAINER_NAME.
To scale (up or down) the replicas of a workload, where TYPE is usually "deployment" or "statefulset"
kubectl scale --replicas=COUNT TYPE/WORKLOAD_NAME
Restart all replicas of a workload:
kubectl rollout restart TYPE/WORKLOAD_NAME
Execute a bash shell inside of a container (if bash is installed):
kubectl exec -it POD_NAME CONTAINER_NAME -- bash
Similarly, any executable installed inside the container can be executed with kubectl exec.
This onboarding guide provides information about Kubernetes. Depending on your role or task you may find that your need for Kubernetes will fluctuate.
The official Kubernetes documentation is quite helpful; however, it can be overwhelming. We recommend glancing through the Concepts and Tasks sections. Furthermore, some useful sub-sections are:
Docker Desktop
Docker Desktop includes the ability to start a single-node Kubernetes cluster and provides the
kubectlclient. (The providedkubectlcan also be used with other Kubernetes clusters.) This Docker Desktop deployment gives you an isolated sandbox to try out Kubernetes concepts and test most aspects of deployments, so it is highly recommended as a first step before interacting with other clusters.Docker Desktop's Kubernetes includes some convenient features, such as
storageClassattribute to use the default.type=LoadBalancersetup a host port mapping like-pwithdocker runThe following screenshot shows how Kubernetes can be enabled from the Docker preferences:
Managed Kubernetes in GCP
Similar to other managed Kubernetes types, GKE takes care of mapping Kubernetes concepts to native Google Cloud constructs. Separate GKE clusters have been configured for development, staging, and production deployments.
The following diagram conveys general GKE concepts with annotations highlighting how these correspond to usage in Salus:
Kubernetes client config
kubectlis the command-line client that you run on your workstation to interact with Kubernetes clusters. If you don't already havekubectl, such as the one provided by Docker Desktop, you can use this documentation to installkubectl.To connect
kubectlto an existing GKE cluster, you will first need to install thegcloudtool. After installation, you may need to rungcloud initto perform initial authentication.With
gcloudinstalled, it is recommended to use the Google Cloud web UI momentarily to locate thegcloudcommand to use for accessing an existing cluster.Access the Kubernetes clusters as shown here:
Locate the desired cluster and click the "Connect" button shown here:
From the pop-up window, click on the copy icon to grab the
gcloudcommand to use:Run the copied command on your workstation to configure a new "kubeconfig" context for that cluster. The default context name is fairly long and ugly, so you can always rename it using
kubectl config rename-context.Common tasks
In general, the official kubectl cheatsheet is a great resource to keep handy; however, the following describes a few specific tasks that we have needed.
To get the current list of pods:
To watch the state of pods, such as after scaling or restart, add
-w:To view and follow the logs of a pod's container:
If a pod has been running for a while, you can start the logs from a relative time offset by adding
--since=DURATION, such as--since=1m. If the pod has more than one container, then you will need to add-c CONTAINER_NAME.To scale (up or down) the replicas of a workload, where
TYPEis usually "deployment" or "statefulset"Restart all replicas of a workload:
Execute a bash shell inside of a container (if bash is installed):
Similarly, any executable installed inside the container can be executed with
kubectl exec.To view the current kubeconfig context:
To switch contexts:
Speaking of switching contexts, krew can be used to easily install plugins into
kubectl. With that you can install thectxplugin. That tool is also available to use stand-alone. With either approach install fzf to access an interactive mode.