Table of Contents
Introduction
Kubernetes (DOKS) is a streamlined management service that enables the deployment of Kubernetes clusters without the hassle of manually managing the control plane and containerized infrastructure. These clusters seamlessly work with standard Kubernetes toolchains, integrate with load balancers and volumes, and can be programmatically controlled through the API and command line.
In this tutorial, you will learn how to set up a the cloud provider managed Kubernetes cluster (DOKS), using the command-line interface. Then, you're going to inspect the cluster state as well as the available features.
Table of contents
- [Prerequisites](#prerequisites)
- [Step 1 – Doctl CLI Introduction](#step-1-doctl-cli-introduction)
- [Step 2 – Authenticating cloud provider API](#step-2-authenticating-the cloud provider-api)
- [Step 3 – Creating the DOKS Cluster](#step-3-creating-the-doks-cluster)
- [Step 4 – Adding a dedicated node for observability](#step-4-optional-adding-a-dedicated-node-for-observability)
- [Conclusion](#conclusion)
Prerequisites
To complete this tutorial, you will need:
- A cloud account for accessing the the cloud provider platform.
- A the cloud provider personal access token for using the cloud provider API.
- Doctl utility for managing the cloud provider resources using the command-line interface.
- Kubectl for Kubernetes cluster interaction.
Step 1 - Doctl CLI Introduction
In this step, you will learn how to use the doctl utility and explore the available options for the the cloud provider platform. The way Doctl works is by using commands and sub-commands to create and manage the cloud provider resources. You can get help for each using the --help flag.
Next, you're going to explore the doctl auth command and sub-commands.
Open a terminal and type the following command to list all the available options for doctl:
doctl --help
The output looks similar to:
doctl is a command line interface (CLI) for the cloud provider API.
Usage:
doctl [command]
Available Commands:
1-click Display commands that pertain to 1-click applications
account Display commands that retrieve account details
apps Display commands for working with apps
auth Display commands for authenticating doctl with an account
balance Display commands for retrieving your account balance
billing-history Display commands for retrieving your billing history
completion Modify your shell so doctl commands autocomplete with TAB
compute Display commands that manage infrastructure
databases Display commands that manage databases
help Help about any command
invoice Display commands for retrieving invoices for your account
kubernetes Displays commands to manage Kubernetes clusters and configurations
monitoring [Beta] Display commands to manage monitoring
projects Manage projects and assign resources to them
registry Display commands for working with container registries
version Show the current version
vpcs Display commands that manage VPCs
...
Next, inspect the auth command help page:
doctl auth --help
The output looks similar to:
The `doctl auth` commands allow you to authenticate doctl for use with your cloud account using tokens that you generate in the control panel at https://developer.mozilla.org/en-US/docs/Web/HTTP.
...
Usage:
doctl auth [command]
Available Commands:
init Initialize doctl to use a specific account
list List available authentication contexts
remove Remove authentication contexts
switch Switches between authentication contexts
...
Then, explore what options are available for the list sub-command (part of the doctl auth command):
doctl auth list --help
The output looks similar to:
List named authentication contexts that you created with `doctl auth init`.
To switch between the contexts use `doctl switch <name>`, where `<name>` is one of the contexts listed.
To create new contexts, see the help for `doctl auth init`.
Usage:
doctl auth list [flags]
...
In the next step, you're going to learn how to authenticate cloud provider API with doctl to create and manage resources on the the cloud provider platform.
Step 2 - Authenticating cloud provider API
Doctl needs to authenticate cloud provider API to perform queries and create resources on your behalf, hence an access token is needed (point 2 from [Prerequisites](#prerequisites)). For each command or sub-command that you run, doctl performs an API call to the cloud provider server.
To authenticate doctl with cloud provider API, you can use the auth command of doctl.
First, list the available options for the auth command:
doctl auth -h
The output looks similar to:
...
Usage:
doctl auth [command]
Available Commands:
init Initialize doctl to use a specific account
list List available authentication contexts
remove Remove authentication contexts
switch Switches between authentication contexts
Next, you're going to use the init sub-command for doctl auth, to perform the initialization (when asked, please enter the personal access token created in the [Prerequisites](#prerequisites) step):
doctl auth init
The output looks similar to:
Please authenticate doctl for use with your cloud account. You can generate a token in the control panel at https://developer.mozilla.org/en-US/docs/Web/HTTP
Enter your access token: <paste_your_personal_token_here>
Validating token... OK
Finally, check that your account is configured for doctl to use:
doctl auth list
The output looks similar to (notice the line containing (current)):
default
doks-starterkit (current)
Next, you're going to learn how to spin up a DOKS cluster and explore the available options.
Step 3 - Creating the DOKS Cluster
In this step, you will learn how to use the doctl k8s command to create a DOKS cluster.
First, explore the available doctl commands for managing DOKS clusters:
Manage a DOKS cluster:
doctl k8s -h
List available options for a DOKS cluster, like region, size, and version:
doctl k8s options -h
List what regions are available to use when creating a DOKS cluster:
doctl k8s options regions
List machine sizes that can be used in a DOKS cluster:
doctl k8s options sizes
List Kubernetes versions that can be used with the cloud provider clusters:
doctl k8s options versions
Display commands for managing Kubernetes clusters:
doctl k8s cluster -h
Next, you will focus on the create sub-command of doctl k8s cluster. Inspect the available options via:
doctl k8s cluster create -h
You will need a DOKS cluster with 3 worker nodes for the Starter Kit tutorial. Use --wait false if you do not want the command to wait until the cluster is ready.
The following example uses 4cpu/8gb AMD nodes ($48/month), 3 default, and auto-scale to 2-4. So, your cluster cost is between $96-$192/month, with hourly billing. To choose a different node type, pick from the following command doctl compute size list.
doctl k8s cluster create starterkit-cluster-2 \
--auto-upgrade=false \
--maintenance-window "saturday=21:00" \
--node-pool "name=basicnp;size=s-4vcpu-8gb-amd;count=3;tag=cluster2;label=type=basic;auto-scale=true;min-nodes=2;max-nodes=4" \
--region nyc1
The output looks similar to:
Notice: Cluster is provisioning, waiting for cluster to be running
..................................................................
Notice: Cluster created, fetching credentials
Notice: Adding cluster credentials to kubeconfig file found in "/Users/starterkit/.kube/config"
Notice: Setting current-context to starterkit-cluster-2
ID Name Region Version Auto Upgrade Status Node Pools
0922a629-7f2e-4bda-940c-4d42a3f987ad starterkit-cluster-2 nyc1 1.21.5-do.0 false running basicnp
Next, you can verify the cluster details. First, fetch your DOKS cluster ID:
doctl k8s cluster list
The output looks similar to the following snippet. Notice the ID column value.
ID Name Region Version Auto Upgrade Status Node Pools
b4ddaa2e-8c0c-4fd8-b249-cbf99eda0808 starterkit-cluster-2 nyc1 1.21.5-do.0 false running basicnp
Now, query the cloud provider API using curl (please make sure to replace the <> placeholders accordingly).
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_do_api_token>" \
https://kubernetes.io/docs/home/;
Finally, check if the kubectl context was set to point to your DOKS cluster. The doctl utility does it automatically for you in general, but just to double-check, run the following:
kubectl config current-context
The output looks similar to:
starterkit-cluster-2
If the above command output is empty or different, you can use the kubeconfig sub-command of doctl k8s cluster to set kubectl context.
First, list the available DOKS clusters:
doctl k8s cluster list
The output looks similar to:
ID Name Region Version Auto Upgrade Status Node Pools
b4ddaa2e-8c0c-4fd8-b249-cbf99eda0808 starterkit-cluster-2 nyc1 1.21.5-do.0 false running basicnp
Next, set kubectl context to point to your cluster:
doctl kubernetes cluster kubeconfig save <your_cluster_name>
The output looks similar to:
Notice: Adding cluster credentials to kubeconfig file found in "/Users/starterkit/.kube/config"
Notice: Setting current-context to starterkit-cluster-2
Finally, list DOKS cluster nodes:
kubectl get nodes
The output looks similar to:
NAME STATUS ROLES AGE VERSION
basicnp-865x3 Ready <none> 2m55s v1.21.5
basicnp-865x8 Ready <none> 2m21s v1.21.5
basicnp-865xu Ready <none> 2m56s v1.21.5
If everything is set correctly, you should get a list of all the DOKS cluster worker nodes. The STATUS column should print Ready if all the nodes are healthy.
[info] If the worker node(s) STATUS is different from Ready, you can inspect the affected node(s) via:
kubectl describe node <worker_node_name>
After running the above command, look at the Events section to check if something went wrong. There are many other useful sections to look at, like Conditions, System Info, and Allocated resources to help you troubleshoot worker node issues in the future.
Step 4 [OPTIONAL] - Adding a dedicated node for observability
If you plan to use this cluster to serve in a production environment, it is recommended that you also set up, apart from the basic nodes, another fixed-size node pool with the purpose of serving the observability stack. In general, it is good practice to separate the observability stack from user applications. This way, one cannot interfere with another or get affected by downtime when performing cluster or node pool maintenance, etc. On the other hand, monitoring is a crucial aspect of any modern infrastructure hence high availability is a must. Later on, you will use Node affinity to schedule observability-related pods on the dedicated node pool.
To add another node pool to the cluster created earlier run the following command:
doctl kubernetes cluster node-pool create starterkit-cluster-2 \
--name "observability" \
--size "s-4vcpu-8gb-amd" \
--min-nodes 1 \
--max-nodes 1 \
--count 1
The output looks similar to:
ID Name Size Count Tags
7b5037c8-637c-4a8b-abbe-3296b5aa92fa observability s-4vcpu-8gb-amd 1 k8s,k8s:1dcda264-15d6-4bcb-92b1-e64d236f59c1,k8s:worker
Next, check the cluster's nodes created:
kubectl get nodes
The output looks similar to the following snippet. Notice the observability prefix in the node name.
NAME STATUS ROLES AGE VERSION
basicnp-c4k0f Ready <none> 2m34s v1.22.11
basicnp-c4k0q Ready <none> 2m38s v1.22.11
basicnp-c4k0y Ready <none> 2m38s v1.22.11
observability-cd111 Ready <none> 2m44s v1.22.11
Next, you will add a label to the new node. This will make it easier to schedule pods onto this node using a distinct label and node affinity.
kubectl label nodes <YOUR_NODE_NAME> preferred=observability
Verify that your node has a preferred=observability label:
kubectl get nodes <YOUR_NODE_NAME> --show-labels
The output looks similar to:
NAME STATUS ROLES AGE VERSION LABELS
observability-cd111 Ready <none> 9m27s v1.22.8 beta.kubernetes.io/arch=amd64,beta.kubernetes.io/instance-type=s-4vcpu-8gb-amd,beta.kubernetes.io/os=linux,www.progressiverobot.com/node-id=eb199834-a852-40fe-9785-42c361536ec0,www.progressiverobot.com/node-pool-id=92e14637-73d1-4703-a902-11fef09ca4f2,www.progressiverobot.com/node-pool=observability,www.progressiverobot.com/version=1.22.8-do.1,failure-domain.beta.kubernetes.io/region=nyc3,kubernetes.io/arch=amd64,kubernetes.io/hostname=observability-cd111,kubernetes.io/os=linux,node.kubernetes.io/instance-type=s-4vcpu-8gb-amd,preferred=observability,region=nyc3,topology.kubernetes.io/region=nyc3
Conclusion
In this tutorial, you learned how to use the doctl utility, inspect the available options as well as how to get help for a specific command or sub-command. Then, you learned how to create a DOKS cluster and inspect the worker node's state.
Learn More
In the next section, you will learn how to use the container registry (DOCR) to easily store and manage private container images for your Kubernetes cluster.
