Merge branch 'feature/docs-user-data' into 'main'

Add documentation for the user-data modules

See merge request alpine/cloud/tiny-cloud!135

.gitlab-ci.yml

@@ -8,11 +8,12 @@ test-default:
     - docker-alpine
     - x86_64
 
-test-dash:
-  extends: test-default
-  before_script:
-    - apk add dash
-    - ln -sf /usr/bin/dash /bin/sh
+# disabled - 0.13.1 has globbing bug
+#test-dash:
+#  extends: test-default
+#  before_script:
+#    - apk add dash
+#    - ln -sf /usr/bin/dash /bin/sh
 
 test-oksh:
   extends: test-default

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2025:12-07 - Tiny Cloud v3.2.3
+
+* Correctly identify empty `user-data` content instead of flagging it as "unknown".
+
 ## 2025-06-11 - Tiny Cloud v3.2.2
 
 * Fix `Makefile` to dynamically generate the list of clouds, allowing the new

TODO.md

@@ -18,6 +18,10 @@
 
 * Support additional features of `#cloud-config` as needed
 
+* Support for multipart `user-data` payload?
+
+* Support for `#network-config`?
+
 * Support LVM partitioning and non-`ext[234]` filesystems?
 
 * Support other cloud providers...

lib/tiny-cloud/init

@@ -178,9 +178,11 @@ init__create_default_user() {
 		echo '%wheel ALL=(ALL) NOPASSWD: ALL' > "$ETC/sudoers.d/wheel"
 	fi
 	if [ -d "$ETC/doas.d" ]; then
-		echo 'permit nopass :wheel' > "$TARGET/etc/doas.d/wheel.conf"
+		echo 'permit nopass :wheel' > "$ETC/doas.d/wheel.conf"
+		#echo 'permit nopass :wheel' > "$TARGET/etc/doas.d/wheel.conf"
 	elif [ -f "$ETC/doas.conf" ]; then
-		add_once "$TARGET/etc/doas.conf" "permit nopass :wheel"
+		add_once "$ETC/doas.conf" "permit nopass :wheel"
+		#add_once "$TARGET/etc/doas.conf" "permit nopass :wheel"
 	fi
 }
 
@@ -294,6 +296,9 @@ userdata_type() {
 	if [ ! -f "$TINY_CLOUD_VAR/user-data" ]; then
 		echo missing
 		return
+	elif [ ! -s "$TINY_CLOUD_VAR/user-data" ]; then
+		echo empty
+		return
 	fi
 	header=$(head -n1 "$TINY_CLOUD_VAR/user-data" | sed -e 's/[[:space:]].*//g')
 	case "$header" in

lib/tiny-cloud/user-data/empty

@@ -0,0 +1,9 @@
+# Empty UserData Functions
+# vim:set filetype=sh:
+# shellcheck shell=sh
+
+init__empty_userdata() {
+	log -i -t "$phase" notice "$ACTION: empty user-data found"
+}
+
+INIT_ACTIONS_MAIN="empty_userdata ${INIT_ACTIONS_MAIN}"

tests/init.test

@@ -197,6 +197,11 @@ userdata_type_body() {
 			-o match:"missing" \
 			sh -c ". \"$lib\"; userdata_type"
 
+		touch var/lib/cloud/user-data
+		CLOUD="$c" atf_check \
+			-o match:"empty" \
+			sh -c ". \"$lib\"; userdata_type"
+
 		echo "#tiny-cloud-config" > var/lib/cloud/user-data
 		CLOUD="$c" atf_check \
 			-o match:"tiny-cloud-config" \

tests/tiny-cloud-alpine.test

@@ -32,6 +32,7 @@ init_tests \
 	userdata_users_groups \
 	userdata_users_lock_passwd \
 	userdata_users_doas \
+	userdata_users_doas_with_default \
 	userdata_users_ssh_authorized_keys \
 	userdata_ssh_authorized_keys \
 	userdata_groups \
@@ -420,6 +421,26 @@ userdata_users_doas_body() {
 		|| atf_fail "etc/doas.d/foo.conf is not as expected"
 }
 
+userdata_users_doas_with_default_body() {
+	# first specified user keeps the default user
+	fake_userdata_nocloud <<-EOF
+		#cloud-config
+		users:
+		  - default
+		  - name: foo
+		    doas: ["permit nopass foo"]
+	EOF
+	mkdir -p etc/doas.d
+	atf_check -e ignore -o ignore tiny-cloud early
+	atf_check \
+		-e match:"userdata_users: done" \
+		-o ignore \
+		tiny-cloud main
+	find .
+	grep "permit nopass foo" etc/doas.d/foo.conf \
+		|| atf_fail "etc/doas.d/foo.conf is not as expected"
+}
+
 userdata_users_ssh_authorized_keys_body() {
 	fake_bin getent <<-EOF
 		#!/bin/sh
@@ -923,4 +944,3 @@ userdata_autoinstall_lvm_body() {
 		-o match:"reboot" \
 		tiny-cloud final
 }
-

user-data-file.md

@@ -0,0 +1,93 @@
+# User Data
+
+User-data file is loaded during early stage. Location of this file defined by kernel paramter: `ds=<provider>;s=<path>`. For example for nocloud provider: `ds=nocloud;s=http://my.miniserve.instance/tinycloud/` tiny cloud will search for a file with name "user-data" at http://my.miniserve.instance/tinycloud/ resource.
+
+Tiny-Cloud currently supports several user-data types and you could use ONE of them:
+
+- alpine-config
+- cloud-config
+- script
+
+The `user-data` file is used to configure Alpine Linux state at the boot time. It supports a variety of modules that can be used to install packages, configure users and groups, and more.
+
+## Alpine-Config Data Type
+
+Alpine config Must have `#alpine-config` as fist line in the file.
+Rest of the file is a yaml which describes several alpine-spesific configuration paramters:
+
+```yaml
+#alpine-config
+apk:
+  cache: # path to apk cache where /etc/apk/cache link follows
+  repositories: # <map> defines resulted url https://dl-cdn.alpinelinux.org/alpine/edge/community
+    - base_url: # The base usr of the repository ( https://dl-cdn.alpinelinux.org/alpine )
+      version: # (optional) examples: [ 3.16 | 3.21 | edge ]  if not set will be retrieved from the system
+      repos: # <list>
+        - community
+
+autoinstall: # [ true | false] install alpine on the biggest empty disk found in the system
+```
+
+## Cloud-Config Data Type
+
+Alpine config Must have `#cloud-config` as fist line in the file.
+
+```yaml
+#cloud-config
+user: # <map> sets default user
+  name: # <string>
+
+groups: # <list> groups for default user
+  - wheel
+  - admin
+
+users: # <list>
+  # first one become default user
+  - name:
+    homedir:
+    shell:
+    primary_group:
+    gecos: # description for the user
+    system: # [ true | false ] create a system user
+    no_create_home: # [ true | false ] do not create home directory for the user. Default: false
+    lock_passwd: # reset password of the user
+    ssh_authorized_keys: # <list>
+    groups: wheel,power # comma-separated list of groups for the user
+    doas: # content of the /etc/doas.d/<name>.conf doas file
+      -
+
+ssh_authorized_keys: # public key to be authorized as default user
+
+write_files: # <list> Writes content of the file to the system. Can be used to define configuration files.
+  - path: # destination path of the file (required)
+    permissions: # file mode (default 0644)
+    owner: # owner:group of the file (default root:root)
+    encoding: # provided endoding of the file [gzip|gz|gz+base64|gzip+base64|gz+b64|gzip+b64|base64|b64|text/plain] (default text/plain)
+    append: # if "true", then content will be added to the end of the file
+    content: | # (required)
+      here is multiline
+      content of your file
+
+ntp:
+  enabled: # checks for [ yes | true ]. Otherwise do not enables ntp service
+  ntp_client: # [ ntpd | chrony | openntpd ] (default: chrony)
+
+package_update: # if "true" runs `apk update`
+
+package_upgrade: # if "true" runs `apk upgrade`
+
+packages: # <list>
+  - curl
+  - bash
+```
+
+## Script Data Type
+
+Scipt user-data could be used to run arbitrary user script at the system init. User-data file must have script executor specific shebang, started with `#!`
+For example shell script:
+
+```shell
+#!/bin/sh
+
+echo "running custom script at init time"
+```