Add basic/intermediate and advanced provisioning tutorials (coreos#134)

Tutorials imported from Dusty Mabe's Devconf.cz 2020 Fedora CoreOS Lab: https://dustymabe.com/2020/01/23/devconf.cz-2020-fedora-coreos-lab/ Fixes: coreos#106
jbtrystram · Aug 5, 2020 · 8ad52c8 · 8ad52c8
1 parent e8dfdc7
commit 8ad52c8
Show file tree

Hide file tree

Showing 5 changed files with 761 additions and 0 deletions.
diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
@@ -34,3 +34,7 @@
 ** xref:migrate-cl.adoc[Migrating from Container Linux]
 * Reference pages
 ** xref:platforms.adoc[Platforms]
+* xref:tutorials.adoc[Tutorials]
+** xref:tutorial-basic-provisioning-and-customization.adoc[Basic Provisioning with Fedora CoreOS]
+** xref:tutorial-intermediate-provisioning.adoc[Intermediate Provisioning Scenario]
+** xref:tutorial-advanced-provisioning.adoc[Advanced Provisioning Scenario]
diff --git a/modules/ROOT/pages/tutorial-advanced-provisioning.adoc b/modules/ROOT/pages/tutorial-advanced-provisioning.adoc
@@ -0,0 +1,289 @@
+= Booting Fedora CoreOS: Advanced Provisioning Scenario
+
+This tutorial begin where xref:intermediate-provisioning-tutorial.adoc[Intermediate Provisioning Tutorial] left off.
+Where we provisioned a Fedora CoreOS instance to add a systemd dropin, disable automatic updates, added an executable script to run on boot and configured a systemd service to run the script on first boot.
+
+So, what is running a server all about? Hosting services, crunching data ? *DING DING DING!*
+Let's actually do something with out Fedora CoreOS node.
+
+Since Fedora CoreOS is focused on running applications/services in containers we recommend trying to only run containers and not modifying the host directly.
+This makes automaic updates more reliable and allows for seperation of concerns with the Fedora CoreOS team responsible for the OS and end-user operators/sysadmins responsible for the applications.
+
+In this case let's do a few more things. As usual we'll do the autologin and disabling of updates, but we'll also:
+
+* Add an SSH Key fot the `core` user.
+* Add a systemd service (`failure.service`) that fails on boot.
+* Add a systemd service that will use a container to bring up a hosted service.
+
+We'll create this config in a file called `./fcct-advanced.yaml`
+
+[source,yaml]
+----
+[host]$ cat fcct-advanced.yaml
+variant: fcos
+version: 1.0.0
+passwd:
+  users:
+    - name: core
+      ssh_authorized_keys:
+        - ssh-rsa AAAA...
+systemd:
+  units:
+    - name: [email protected]
+      dropins:
+      - name: autologin-core.conf
+        contents: |
+          [Service]
+          # Override Execstart in main unit
+          ExecStart=
+          # Add new Execstart with `-` prefix to ignore failure
+          ExecStart=-/usr/sbin/agetty --autologin core --noclear %I $TERM
+          TTYVTDisallocate=no
+    - name: failure.service
+      enabled: true
+      contents: |
+        [Service]
+        Type=oneshot
+        ExecStart=/usr/bin/false
+        RemainAfterExit=yes
+        [Install]
+        WantedBy=multi-user.target
+    - name: etcd-member.service
+      enabled: true
+      contents: |
+        [Unit]
+        Description=Run single node etcd
+        After=network-online.target
+        Wants=network-online.target
+        [Service]
+        ExecStartPre=mkdir -p /var/lib/etcd
+        ExecStartPre=-/bin/podman kill etcd
+        ExecStartPre=-/bin/podman rm etcd
+        ExecStartPre=-/bin/podman pull quay.io/coreos/etcd
+        ExecStart=/bin/podman run --name etcd --net=host \
+                    --volume /var/lib/etcd:/etcd-data:z  \
+                    quay.io/coreos/etcd:latest /usr/local/bin/etcd              \
+                            --data-dir /etcd-data --name node1                  \
+                            --initial-advertise-peer-urls http://127.0.0.1:2380 \
+                            --listen-peer-urls http://127.0.0.1:2380            \
+                            --advertise-client-urls http://127.0.0.1:2379       \
+                            --listen-client-urls http://127.0.0.1:2379          \
+                            --initial-cluster node1=http://127.0.0.1:2380
+        ExecStop=/bin/podman stop etcd
+        [Install]
+        WantedBy=multi-user.target
+storage:
+  files:
+    - path: /etc/zincati/config.d/90-disable-auto-updates.toml
+      contents:
+        inline: |
+          [updates]
+          enabled = false
+----
+
+_Optional:_ You can replace the SSH pubkey in the yaml file with your own public key so you can log in to the booted instance. If you choose not to do this you'll still be auto logged in to the serial console.
+
+Run `fcct` to convert that to an ignition config:
+
+[source,bash]
+----
+[host]$ fcct --pretty --strict fcct-advanced.yaml --output advanced.ign
+----
+
+Now let's provision it:
+
+[source, bash]
+----
+[host]$ chcon --verbose unconfined_u:object_r:svirt_home_t:s0 advanced.ign
+[host]$ virt-install --name=fcos --vcpus=2 --ram=2048 --import \
+            --network=bridge=virbr0 --graphics=none \
+            --qemu-commandline="-fw_cfg name=opt/com.coreos/config,file=${PWD}/advanced.ign" \
+            --disk=size=20,backing_store=${PWD}/fedora-coreos[stream_version].qcow2
+----
+
+On the serial console you see:
+
+[source,bash]
+----
+Fedora CoreOS preview 32.20200108.3.0
+Kernel 5.6.7-200.fc32.x86_64 on an x86_64 (ttyS0)
+
+eth0: 192.168.122.163 fe80::5054:ff:fe73:6081
+localhost login: core (automatic login)
+
+[systemd]
+Failed Units: 1
+  failure.service
+----
+
+If you’d like to connect via SSH disconnect from the serial console by pressing `CTRL` + `]` and then use the reported IP address for `eth0` from the serial console to log in using the `core` user via SSH:
+
+[source,bash]
+----
+$ ssh [email protected]
+The authenticity of host '192.168.122.163 (192.168.122.163)' can't be established.
+ECDSA key fingerprint is SHA256:OAmR5Ab5eH9eZHC+D1gYmRsoUgJ/jufTNArrskBCxr4.
+Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
+Warning: Permanently added '192.168.122.163' (ECDSA) to the list of known hosts.
+Fedora CoreOS preview 32.20200108.3.0
+Tracker: https://github.com/coreos/fedora-coreos-tracker
+Preview release: breaking changes may occur
+
+Last login: Mon Jan 20 22:15:10 2020
+[systemd]
+Failed Units: 1
+  failure.service
+----
+
+*NOTE:* IP address can differ according to your network bridge settings.
+
+The `Failed Units` message is coming from the https://github.com/coreos/console-login-helper-messages[console login helper messages] helpers.
+This particular helper shows us when `systemd` has services that are in a failed state.
+In this case we made `failure.service` with `ExecStart=/usr/bin/false`, so we intentionally created a service that will always fail in order to illustrate the helper messages.
+
+Now that we’re up and we don’t have any real failures we can check out our service we care about (`etcd-member.service`):
+
+[source,bash]
+----
+$ systemctl status etcd-member.service
+● etcd-member.service - Run single node etcd
+   Loaded: loaded (/etc/systemd/system/etcd-member.service; enabled; vendor preset: enabled)
+   Active: active (running) since Mon 2020-01-20 22:15:09 UTC; 4min 5s ago
+  Process: 1144 ExecStartPre=/usr/bin/mkdir -p /var/lib/etcd (code=exited, status=0/SUCCESS)
+  Process: 1153 ExecStartPre=/bin/podman kill etcd (code=exited, status=125)
+  Process: 1356 ExecStartPre=/bin/podman rm etcd (code=exited, status=1/FAILURE)
+  Process: 1396 ExecStartPre=/bin/podman pull quay.io/coreos/etcd (code=exited, status=0/SUCCESS)
+ Main PID: 1971 (podman)
+    Tasks: 10 (limit: 2297)
+   Memory: 115.7M
+   CGroup: /system.slice/etcd-member.service
+           └─1971 /bin/podman run --name etcd --net=host --volume /var/lib/etcd:/etcd-data:z quay.io/coreos/etcd:latest /usr/local/bin/etcd --data-dir /etcd-data --name node1 --initial-adv>
+
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.486290 I | raft: b71f75320dc06a6c became candidate at term 2
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.486327 I | raft: b71f75320dc06a6c received MsgVoteResp from b71f75320dc06a6c at term 2
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.486344 I | raft: b71f75320dc06a6c became leader at term 2
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.486351 I | raft: raft.node: b71f75320dc06a6c elected leader b71f75320dc06a6c at term 2
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.486698 I | etcdserver: published {Name:node1 ClientURLs:[http://127.0.0.1:2379]} to cluster 1c45a069f3a1d796
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.487238 I | etcdserver: setting up the initial cluster version to 3.3
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.487310 I | embed: ready to serve client requests
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.488046 N | embed: serving insecure client requests on 127.0.0.1:2379, this is strongly discouraged!
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.498083 N | etcdserver/membership: set the initial cluster version to 3.3
+Jan 20 22:15:10 localhost podman[1971]: 2020-01-20 22:15:10.498521 I | etcdserver/api: enabled capabilities for version 3.3
+----
+
+We can also inspect the state of the container that was run by the systemd service:
+
+[source,bash]
+----
+$ sudo podman ps -a
+CONTAINER ID  IMAGE                       COMMAND               CREATED        STATUS            PORTS  NAMES
+85cf5d500626  quay.io/coreos/etcd:latest  /usr/local/bin/et...  4 minutes ago  Up 4 minutes ago         etcd
+----
+
+And we can set a key/value pair in etcd. For now let’s set the key `fedora` to the value `fun`:
+
+[source,bash]
+----
+$ curl -L -X PUT http://127.0.0.1:2379/v2/keys/fedora -d value="fun"
+{"action":"set","node":{"key":"/fedora","value":"fun","modifiedIndex":4,"createdIndex":4}}
+$ curl -L http://127.0.0.1:2379/v2/keys/ 2>/dev/null | jq .
+{
+  "action": "get",
+  "node": {
+    "dir": true,
+    "nodes": [
+      {
+        "key": "/fedora",
+        "value": "fun",
+        "modifiedIndex": 4,
+        "createdIndex": 4
+      }
+    ]
+  }
+}
+----
+Looks like everything is working!
+
+== Updates!
+
+So far we’ve been disabling one of the best features of Fedora CoreOS: automatic updates.
+Let’s see them in action.
+
+We can do this by removing the `zincati` config that is disabling the updates and restarting the zincati service:
+
+[source,bash]
+----
+$ sudo rm /etc/zincati/config.d/90-disable-auto-updates.toml
+$ sudo systemctl restart zincati.service
+Connection to 192.168.122.163 closed.
+----
+
+After restarting `zincati.service` the machine will reboot after a short period of time.
+In this case the update has been staged and the system rebooted in order to boot into the new deployment with the latest software.
+
+When we log back in we can view the current version of Fedora CoreOS is now `31.20200113.3.1`.
+The rpm-ostree status output will also how the older version, which still exists in case we need to rollback:
+
+[source,bash]
+----
+$ rpm-ostree status
+State: idle
+AutomaticUpdates: disabled
+Deployments:
+● ostree://fedora:fedora/x86_64/coreos/stable
+                   Version: 31.20200113.3.1 (2020-01-14T00:20:15Z)
+                    Commit: f480038412cba26ab010d2cd5a09ddec736204a6e9faa8370edaa943cf33c932
+              GPGSignature: Valid signature by 7D22D5867F2A4236474BF7B850CB390B3C3359C4
+
+  ostree://fedora:fedora/x86_64/coreos/stable
+                   Version: 31.20200108.3.0 (2020-01-09T21:51:07Z)
+                    Commit: 113aa27efe1bbcf6324af7423f64ef7deb0acbf21b928faec84bf66a60a5c933
+              GPGSignature: Valid signature by 7D22D5867F2A4236474BF7B850CB390B3C3359C4
+----
+
+*NOTE:* The currently booted deployment is denoted by the `●` character.
+
+You can view the differences between the two versions by running an `rpm-ostree db diff` command:
+
+[source,bash]
+----
+$ rpm-ostree db diff 113aa27efe1bbcf6324af7423f64ef7deb0acbf21b928faec84bf66a60a5c933 f480038412cba26ab010d2cd5a09ddec736204a6e9faa8370edaa943cf33c932
+ostree diff commit from: 113aa27efe1bbcf6324af7423f64ef7deb0acbf21b928faec84bf66a60a5c933
+ostree diff commit to:   f480038412cba26ab010d2cd5a09ddec736204a6e9faa8370edaa943cf33c932
+Upgraded:
+  bind-libs 32:9.11.13-3.fc31 -> 32:9.11.14-2.fc31
+  ...
+----
+
+If the system is not functioning fully for whatever reason we can go back to the previous version:
+
+[source,bash]
+----
+$ sudo rpm-ostree rollback --reboot
+----
+
+After logging back in after reboot we can see we are now booted back into the old `31.20200108.3.0` deployment from before the upgrade occurred:
+
+[source,bash]
+----
+$ rpm-ostree status
+State: idle
+AutomaticUpdates: disabled
+Deployments:
+● ostree://fedora:fedora/x86_64/coreos/stable
+                   Version: 31.20200108.3.0 (2020-01-09T21:51:07Z)
+                    Commit: 113aa27efe1bbcf6324af7423f64ef7deb0acbf21b928faec84bf66a60a5c933
+              GPGSignature: Valid signature by 7D22D5867F2A4236474BF7B850CB390B3C3359C4
+
+  ostree://fedora:fedora/x86_64/coreos/stable
+                   Version: 31.20200113.3.1 (2020-01-14T00:20:15Z)
+                    Commit: f480038412cba26ab010d2cd5a09ddec736204a6e9faa8370edaa943cf33c932
+              GPGSignature: Valid signature by 7D22D5867F2A4236474BF7B850CB390B3C3359C4
+
+----
+
+== Conclusion
+
+In these tutorials we’ve learned a little bit about Fedora CoreOS.
+We’ve learned how it’s delivered as a pre-created disk image, how it’s provisioned in an automated fashion via Ignition, and also how automated updates are configured and achieved via zincati and RPM-OSTree.
+The next step is to try out Fedora CoreOS for your own use cases and https://github.com/coreos/fedora-coreos-tracker/blob/master/README.md#communication-channels-for-fedora-coreos[join the community]!