DEV Community: Blake Covarrubias

Exploring the HelmChart custom resource in k3s

Blake Covarrubias — Sun, 08 Sep 2019 18:24:40 +0000

k3s is a lightweight Kubernetes distribution developed by Rancher which is suitable for edge, IoT, and resource-constrained computing environments.

Helm is a package manager for Kubernetes which enables users to find, share, and use software built for Kubernetes.

Traditionally, Helm is comprised of a client (helm) and server-side component, Tiller, which manages the deployment and lifecycle of Helm charts. In k3s, Tiller is replaced by Helm Controller. Helm Controller defines a new HelmChart custom resource definition, or CRD, for managing Helm charts.

You can verify the HelmChart resource is present on a k3s cluster by using kubectl to list the available API resources.

 $ sudo k3s kubectl api-resources --api-group=helm.cattle.io
NAME         SHORTNAMES   APIGROUP         NAMESPACED   KIND
helmcharts                helm.cattle.io   true         HelmChart

The HelmChart resource

Below is an example of a HelmChart resource definition.

---
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata: # Kubernetes object metadata
  name: # Chart name (required)
  namespace: kube-system # Namespace Helm Controller is monitoring to deploy charts (required)
spec: # resource specification

The apiVersion and kind fields together identify this as a HelmChart resource to be managed by Helm Controller.

The name field under metadata specifies a name for the HelmChart resource. namespace specifies the Kubernetes namespace in which Helm Controller is monitoring CRDs. For k3s, this must be kube-system as Helm Controller is only configured to watch this namespace for new HelmChart resources.

Lastly, the spec, or specification, field is used to specify the desired state of the HelmChart resource.

HelmChart resource `spec`

The HelmChart resource supports several configuration parameters. These parameters correspond to helm install command line arguments and are passed to Helm during chart deployment.

chart (string: null) - Chart reference or a URL.
targetNamespace (string: null) - Namespace to install the Chart into. Defaults to the namespace used by the k3s controller (i.e., kube-system) if omitted.
version (string: null) The exact Chart version to install. If this is not specified, the latest version is installed.
repo (string: null) - Chart repository URL where to locate the requested Chart.
set (string: null) - A dictionary/map consisting of configuration values to provide to Helm. Keys should be specified as strings. Values may be either Integers or Strings. If more complex values are required, use valuesContent.
valuesContent (string: null) - A list of configuration values to provide to Helm. This should be a multi-line string.

Below is an example of a HelmChart resource definition with all available configuration values defined.

---
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: example-helmchart
  namespace: kube-system
spec:
  chart: test-helmchart
  targetNamespace: test-namespace
  version: 0.0.1
  repo: https://example.com/helm-charts
  set:
    key1: "value1"
    key2: "value2"
  valuesContent: |-
    config:
      application:
        admin_username: admin
        admin_password: insecure_password
      server:
        port: 8080
        tls_enabled: false

The corresponding CLI arguments for this would be:

$ helm install test-helmchart --namespace test-namespace \
                              --version 0.0.1 \
                              --repo https://example.com/helm-charts \
                              --set-string key1=value1 \
                              --set-string key2=value2 \
                              --values values.yaml

Where values.yaml contains the content present under the valuesContent field.

Note: Both set and valuesContent may be used to configure the chart. set only supports strings or integers as values. If other data types are needed, use valuesContent.

Creating a HelmChart

We will now walk through the process of creating a HelmChart resource definition to deploy Node-RED – a flow-based programming for the Internet of Things.

The following steps were performed on a Raspberry Pi 4 running the Raspian operating system. You may need to modify the commands if using a different environment.

First, create a file named node-red-helmchart.yaml using your default editor.

$ editor node-red-helmchart.yaml

Copy and paste the following block of text into the file.

---
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: node-red
  namespace: kube-system
spec:
  chart: stable/node-red
  targetNamespace: node-red
  set:
    image.tag: rpi
  valuesContent: |-
    ingress:
      enabled: "true"
      annotations:
        kubernetes.io/ingress.class: traefik
        traefik.ingress.kubernetes.io/rule-type: PathPrefixStrip
      hosts:
        - raspberrypi1.local
      path: /node-red/

Note: Be sure to modify the ingress.hosts field to contain the hostname and/or IP address of one or more node in your Kubernetes cluster.

The deployment of the chart has been customized by modifying several of the available configuration values. Particularly, Ingress support has been enabled which exposes Node-RED to hosts outside of the Kubernetes cluster at http://raspberrypi1.local/node-red/.

Installing a HelmChart

There are two methods to install a HelmChart in k3s.

Install the resource definition using kubectl apply.
Copy the resource definition to the server's manifest directory at /var/lib/rancher/k3s/server/manifests/.

Installing via kubectl

Instruct Kubernetes to install the specified resource definition using kubectl apply.

$ sudo k3s kubectl apply --filename node-red-helmchart.yaml
helmchart.helm.cattle.io/node-red created

This is the standard method of provisioning resources within Kubernetes.

Installing using Auto-Deploying Manifests

k3s includes a feature called Auto-Deploying Manifests which allows for the automated deployment of Helm charts (and Kubernetes manifests) placed in k3s manifest directory (/var/lib/rancher/k3s/server/manifests). Helm Controller continually watches this directory for new CRDs. When it detects a new resource has been added, it will automatically deploy the chart. Therefore, you can initiate the installation by simply copying node-red-helmchart.yaml into the server's manifest directory.

$ sudo cp node-red-helmchart.yaml /var/lib/rancher/k3s/server/manifests/node-red-helmchart.yaml

Installation process under the hood

Regardless of the installation method used, when a chart is deployed Helm Controller creates a Kubernetes Job which installs the chart into the cluster using helm install.

Execute kubectl get jobs in the kube-system namespace and search for Jobs associated with the deployed chart.

$ sudo k3s kubectl --namespace kube-system get jobs \
                   --selector helmcharts.helm.cattle.io/chart=node-red
NAME                    COMPLETIONS   DURATION   AGE
helm-install-node-red   0/1           21s        23s

You can view the command the Job is executing by re-running kubectl get jobs, and appending additional arguments to select and display Job-specific information using kubectl's custom-column output.

$ export CUSTOM_COLUMN_OUTPUT="COMMAND:.spec.template.spec.containers[0].name,INSTALL_ARGS:.spec.template.spec.containers[0].args"
$ sudo k3s kubectl --namespace kube-system get job helm-install-node-red \
                   --output=custom-columns=$CUSTOM_COLUMN_OUTPUT
COMMAND   INSTALL_ARGS
helm      [install --name node-red stable/node-red --namespace node-red --set-string image.tag=rpi]

The Job installs the chart by executing helm install with the list of installation arguments provided in the HelmChart resource, as noted earlier.

Verifying the chart installation

Verify the chart has been successfully deployed by ensuring the associated resources have been created within the node-red namespace.

$ sudo kubectl --namespace node-red get ingress,service,pods
NAME                          HOSTS                ADDRESS      PORTS   AGE
ingress.extensions/node-red   raspberrypi1.local   10.0.0.133   80      2m2s

NAME               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/node-red   ClusterIP   10.43.135.177   <none>        1880/TCP   2m2s

NAME                            READY   STATUS    RESTARTS   AGE
pod/node-red-7c5c564cb6-sz8b8   1/1     Running   0          2m1s

Updating a HelmChart

The configuration for a chart may be updated using kubectl apply.

$ sudo k3s kubectl apply --filename node-red-helmchart.yaml

Deleting a HelmChart

To delete a Helm Chart, use kubectl delete helmchart.

$ sudo k3s kubectl --namespace kube-system delete helmchart node-red

Conclusion

You have learned about the HelmChart custom resource available in K3s, how to construct a HelmChart resource definition, install it on the cluster, and perform post-deployment operations (update/delete).

That's it for this walkthrough.

I have a written program, k3s-helmchart-generate, which simplifies the process of building HelmChart manifests. You can find a link to the repo on GitHub below.

blake / k3s-helmchart-generate

Helper script to generate HelmChart CRDs for use with k3s

Installing OpenWrt onto a TP-Link TL-MR3020 router via a serial port from macOS

Blake Covarrubias — Tue, 03 Sep 2019 18:33:23 +0000

This is a tutorial for using macOS to install OpenWrt on a TP-Link TL-MR3020 router via a serial port from the CLI.

Target audience

This tutorial is targeted toward individuals possessing basic to intermediate Linux expertise, and who own a TL-MR3020 which is either bricked (i.e., firmware does not load), or to which they do not possess the administrative credentials required to login and flash the firmware from the web interface.

Prerequisites

You will need the following items in order to successfully complete the instructions outlined in this tutorial.

A macOS computer
A TP-Link TL-MR3020 router
1 x USB UART adapter (e.g., Adafruit Industries 954 USB to TTL Serial Cable)
1 x USB A-Male to Mini-B charging cord
1 x Category 5 (CAT5) Ethernet cable
Male to male jumper wires (e.g., Adafruit Industries 1956 Premium Male/Male Jumper Wires - 20 x 3" (75mm))
Internet access

Step 1 - Prepare the environment

Configure a static IP on your Ethernet interface

In order to copy the firmware from your computer to the router you must first configure an IPv4 address on your computer's Ethernet interface so that it may communicate with the router when connected.

To configure an IP on macOS, go to System Preferences > Network and select your Ethernet interface. Click on the dropdown next to Configure IPv4 and select the option 'Manually'.

Configure an IPv4 address such as 192.0.2.2 with a subnet mask of 255.255.255.0.

Click Apply to save the configuration.

Note: This address will not be accessible on your primary network. It will be used solely for communication with the router.

Download the OpenWrt firmware

Head over to OpenWrt's website to download the latest, supported release firmware for the TL-MR3020. Be sure to download the link under the column entitled Firmware OpenWrt Install URL.

At the time of writing, the current supported release is 17.01.5.

Configure the TFTP server

In order to copy the firmware to the device, you will need to set up a Trivial File Transfer Protocol (TFTP) server. This server will be used by the router to download the firmware from your computer.

macOS ships with a TFTP server in the base installation. Use the following launchctl command to temporarily enable the TFTP server under macOS' service manager, launchd.

$ sudo launchctl load -F /System/Library/LaunchDaemons/tftp.plist

The daemon will automatically start upon receiving a network connection request to the computer's IP on either TCP/UDP port number 69 –– the standard TFTP port number.

Next, copy the firmware downloaded in the previous step to the TFTP server's data directory, /private/tftpboot/.

$ sudo cp ~/Downloads/lede-17.01.5-ar71xx-generic-tl-mr3020-v1-squashfs-factory.bin /private/tftpboot/

Step 2 - Open the device

The top of the router comes off with a bit of prying. Insert a plastic tool to carefully pry open the plastic top.

Step 3 - Connect the USB adapter to the UART pins on the router

Plug the USB adapter into your computer.

Next, connect the transmit, receive, and ground wires from the UART adapter to the associated pins on the router which are highlighted in the following picture just below the RAM.

The order of the pins from left to right is: Power, Ground (GND), Receive (RXD), and Transmit (TXD).

Using the jumper wires, connect the cables from the USB UART adapter to the UART pins on the router's board. The resultant connections should be:

TL-MR3020	USB-UART	COLOR
GND	GND	BLACK
RXD	TXD	GREEN
TXD	RXD	WHITE

Note: Be sure to swap the TXD and RXD when connecting to the router.

Step 4 - Connect the Ethernet cable to the router

Connect the Ethernet cable between your computer and the router's Ethernet port.

Step 5 - Initiate a console connection to the router

Open a Unix console on macOS using a terminal emulator such as the built-in Terminal application (Applications > Utilities > Terminal) or iTerm2.

Next, use the cu command which is built into macOS to initiate a console connection from your computer to the router. Alternatively, you can use a GUI-based serial console program such as CoolTerm or Serial from DecisiveTactics.

You will need to provide cu the name of your TTY device, and a baud rate of 115200 bits per second to use for the connection.

cu --line /dev/tty.SLAB_USBtoUART --speed 115200

You will not see any output on your screen until the next step.

Step 6 - Power on the router

Connect the USB A end of your USB cable to either a USB wall charging adapter or a second USB port on your computer.

Connect the mini-B end of your USB cable to the USB port on the router. You should see text output on your terminal screen from the router's boot loader as the router boots.

U-Boot 1.1.4 (Aug 17 2012 - 15:21:03)

AP121 (ar9330) U-boot

DRAM:  32 MB
led turning on for 1s...
id read 0x100000ff
flash size 4194304, sector count = 64
Flash:  4 MB
Using default environment

In:    serial
Out:   serial
Err:   serial
Net:   ag7240_enet_initialize...
No valid address in Flash. Using fixed address
No valid address in Flash. Using fixed address
: cfg1 0x5 cfg2 0x7114
eth0: 00:03:7f:09:0b:ad
ag7240_phy_setup
eth0 up
: cfg1 0xf cfg2 0x7214
eth1: 00:03:7f:09:0b:ad
athrs26_reg_init_lan
ATHRS26: resetting s26
ATHRS26: s26 reset done
ag7240_phy_setup
eth1 up
eth0, eth1
Autobooting in 1 seconds
## Booting image at 9f020000 ...
   Uncompressing Kernel Image ... OK

Starting kernel ...

Before the router boots the kernel, quickly type tpl into the terminal to access the U-Boot console.

There is a very short window in which to type the aforementioned keys before the router begins booting the operating system. You may need to reboot the router, and make multiple attempts to successfully enter the keystrokes.

If successfully entered, you will see the following U-Boot prompt.

hornet>

Fun fact: The TL-MR3020 uses the ALFA Network Hornet-UB embedded board, hence the name 'hornet' in the boot loader's prompt.

Step 7 - Download the firmware onto the router

In order to download the firmware onto the router you must configure an IP address for the router, and set the TFTP server IP as the IP address of your computer.

hornet> setenv ipaddr 192.0.2.10
hornet> setenv serverip 192.0.2.2

Next, use the tftpboot command to download the firmware from the TFTP server to the router. The command takes several argument options.

tftpboot [loadAddress] [bootfilename]

Execute the following to download and install the OpenWrt firmware.

hornet> tftpboot 0x80000000 lede-17.01.5-ar71xx-generic-tl-mr3020-v1-squashfs-factory.bin

You should see output similar to the following if the router is able to connect to router computer and successfully download the firmware.

hornet> tftpboot 0x80000000 lede-17.01.5-ar71xx-generic-tl-mr3020-v1-squashfs-factory.bin
Using eth1 device
TFTP from server 192.0.2.2; our IP address is 192.0.2.10
Filename 'lede-17.01.5-ar71xx-generic-tl-mr3020-v1-squashfs-factory.bin'.
Load address: 0x80000000
Loading: #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         ######################################################
done
Bytes transferred = 3932160 (3c0000 hex)

Make note of the hexadecimal value indicating the number of bytes transferred - in this case, 0x3c0000. This value will be needed later.

Step 8 - Install the firmware onto the router's flash memory

Next, use the erase command to erase the existing flash memory. The help command can be used to provide the syntax of the erase command.

hornet> help erase
...
erase start +len
    - erase FLASH from addr 'start' to the end of sect w/addr 'start'+'len'-1
...

The console output "Booting image at 9f020000 ..." in Step 6 shows the router's current firmware is located at memory address 0x9f020000.

You will need to erase a sufficient amount of space starting from this address to fit the size of the new firmware. Recall the bytes transferred value saved from Step 8. This value will be used as the the +len offset in the erase command.

Execute the following command to erase the flash firmware. You should see the subsequent output upon successful deletion of the specified memory range.

hornet> erase 0x9f020000 +0x3c0000

First 0x2 last 0x3d sector size 0x10000
  61
Erased 60 sectors
hornet>

Then, use copy.b to install the downloaded firmware onto the router's flash memory.

hornet> help cp.b
cp [.b, .w, .l] source target count
    - copy memory

Execute the following.

hornet> cp.b 0x80000000 0x9f020000 0x3c0000
Copy to Flash... write addr: 9f020000
done

Step 9 - Boot the OpenWrt OS

Finally, instruct the router to boot the newly installed OpenWrt firmware.

hornet> bootm 9f020000

The router will be accessible at http://192.168.1.1.

Note: You will need to reconfigure your computer's IP into this subnet before you will be able to access the router at this new address.