From 67850aca32d4c6b3a0431357788173d545ec9bc9 Mon Sep 17 00:00:00 2001
From: Luca Bruno <luca.bruno@coreos.com>
Date: Thu, 4 Oct 2018 09:43:39 +0000
Subject: [PATCH] os: add user-docs on how to use custom torcx remotes and
images
This adds a walk-through and CLC snippets on how to configure custom
remotes and use addons from there.
---
os/torcx-using-custom-remotes.md | 123 +++++++++++++++++++++++++++++++
1 file changed, 123 insertions(+)
create mode 100644 os/torcx-using-custom-remotes.md
diff --git a/os/torcx-using-custom-remotes.md b/os/torcx-using-custom-remotes.md
new file mode 100644
index 000000000..3522bce50
--- /dev/null
+++ b/os/torcx-using-custom-remotes.md
@@ -0,0 +1,123 @@
+# Using custom Torcx remotes
+
+## Remotes Overview
+
+A Torcx [remote][torcx-remotes-design] is a collection of addon images for torcx, served from a remote source, which can be fetched by a node for use by [torcx-generator][torcx-overview].
+Images for configured addons can be retrieved automatically on first-boot provisioning (i.e. in initramfs) and when preparing for new OS updates (i.e. before marking a node as "reboot needed").
+
+## Usage notes
+
+Before starting to configure Torcx remotes, a word of caution on their usage.
+Torcx is not a full package manager, and trying to use it as such may result in unexpected behaviors.
+
+In particular, there is no dependency resolution across addons, and images are supposed to be self-contained and re-built for each specific Container Linux version.
+
+Provisioning images from remotes is coupled with both first-boot setup and OS upgrade mechanisms.
+Configuring an image not available on a remote can result in first-boot provisioning failures or in blocked upgrades.
+
+All of the above behaviors are by-design restrictions in order to minimize possible breakages at runtime.
+
+Unless it is strictly required for very specific usecases, it is usually reccommended not use custom Torcx addons and remotes.
+
+## Provisioning a Torcx remote
+
+Torcx remotes use a reverse-domain naming scheme, and can be configured on nodes during first-boot provisioning via a JSON manifest and an armored OpenPGP keyring.
+The local manifest describes where a Torcx remote is located and which public keys to use for metadata verification, according to the documented [schema][schema-remote-manifest].
+
+A sample remote named `com.example.my-remote` signed by key `4C8413AA38176150A8906994BB1A3A854F3BBEBF` can be provisioned with the following [Container Linux Config][ct-configs] snippet:
+
+```yaml container-linux-config
+storage:
+ files:
+ - path: /etc/torcx/remotes/com.example.my-remote/remote.json
+ filesystem: root
+ mode: 0640
+ contents:
+ inline: |
+ {
+ "kind": "remote-manifest-v0",
+ "value": {
+ "base_url": "https://torcx-remotes.example.com/my-remote/${COREOS_BOARD}/${VERSION_ID}/",
+ "keys": [
+ { "armored_keyring": "4C8413AA38176150A8906994BB1A3A854F3BBEBF.pgp.asc" }
+ ]
+ }
+ }
+
+ - path: /etc/torcx/remotes/com.example.my-remote/4C8413AA38176150A8906994BB1A3A854F3BBEBF.pgp.asc
+ filesystem: root
+ mode: 0640
+ contents:
+ inline: |
+ -----BEGIN PGP PUBLIC KEY BLOCK-----
+
+ mQINBFPOTCkBEADVqHsjLwgh9RrDln/oOS3MQgYnYhI72IpAiNhp9j+kdKWCrc7S
+ [...]
+ DQzFS07A45A=
+ =dYyN
+ -----END PGP PUBLIC KEY BLOCK-----
+```
+
+The base URL for a remote is a templated string which is evaluated at runtime for simple variable substitution.
+Commonly used variables include:
+
+ * `${COREOS_BOARD}`: board type (e.g. "amd64-usr")
+ * `${VERSION_ID}`: OS version (e.g. "1680.2.0")
+ * `${ID}`: OS vendor ID (e.g. "coreos")
+
+
+## Enabling a Torcx addon from a remote
+
+In order to use a Torcx addon from a remote, it must be configured in the active profile and it should reference the remote where it can be located.
+
+After having configured the remote `com.example.my-remote`, provisioning an addon named `my-addon` at version `1` out of it can be done with the following configuration snippet:
+
+```yaml container-linux-config
+storage:
+ files:
+ - path: /etc/torcx/profiles/my-profile.json
+ filesystem: root
+ mode: 0640
+ contents:
+ inline: |
+ {
+ "kind": "profile-manifest-v1",
+ "value": {
+ "images": [
+ {
+ "name": "my-addon",
+ "reference": "1",
+ "remote": "com.example.my-remote"
+ }
+ ]
+ }
+ }
+
+ - path: /etc/torcx/next-profile
+ filesystem: root
+ mode: 0640
+ contents:
+ inline: "my-profile\n"
+```
+
+Please note that a single user-profile can be active at any point, thus further customizations should be done directly against the profile manifest above.
+
+## Behavior on updates
+
+Whenever a new OS update is available and before applying it to the running node, [Update Engine][update_engine] checks and tries to provision all configured Torcx addons from remotes.
+
+If it is not possible to provision any of the configured addons for the upcoming OS, the update will not applied and the process will be re-tried later.
+
+This can happen if an addon is not anymore present on a remote, if the image matching the new OS version is not yet available, or in case of any other error when fetching from a remote.
+
+In that case, errors will be logged to the system journal and can be inspected as follows:
+
+```
+$ sudo journalctl -t coreos-postinst
+```
+
+[torcx-remotes-design]: https://github.com/coreos/torcx/blob/master/Documentation/design/remotes.md
+[torcx-overview]: torcx-overview.md
+[schema-remote-manifest]: https://github.com/coreos/torcx/blob/master/Documentation/schemas/remote-manifest-v0.md
+[ct-configs]: provisioning.md
+[update_engine]: https://github.com/coreos/update_engine