Merge pull request #283 from coreos/docs

Documentation,CHANGES.md: Update documentation for v0.4.0
poseidon · Jul 20, 2016 · 4e4450a · 4e4450a
2 parents 6d36497 + d8f3cea
commit 4e4450a
Show file tree

Hide file tree

Showing 14 changed files with 259 additions and 285 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -2,44 +2,53 @@
 
 ## Latest
 
-* TLS Authentication:
+## v0.4.0 (2016-06-21)
+
+#### Features
+
+* Add/improve rkt, Docker, Kubernetes, and binary/systemd deployment docs
+* TLS Client Authentication:
     * Add gRPC API TLS and TLS client-to-server authentication (#140)
     * Enable gRPC API by providing a TLS server `-cert-file` and `-key-file`, and a `-ca-file` to authenticate client certificates
-    * Provide `bootcmd` tool a TLS client `-cert-file` and `-key-file`, and a `-ca-file` to verify the server identity.
+    * Provide the `bootcmd` tool a TLS client `-cert-file` and `-key-file`, and a `-ca-file` to verify the server identity.
 * Improvements to Ignition Support:
-    * Allow Ignition 2.0.0 JSON and YAML template files (#141)
+    * Allow Fuze YAML template files for Ignition 2.0.0 (#141)
     * Stop requiring Ignition templates to use file extensions (#176)
 * Logging Improvements:
-    * Show `bootcfg` message at the home path `/`
     * Add structured loggging with Logrus (#254, #268)
-    * Log requests for bootcfg hosted assets (#214)
+    * Log requests for bootcfg assets (#214)
+    * Show `bootcfg` message at the home path `/`
     * Fix http package log messages (#173)
-    * Error when a template is rendered with a machine Group which is missing a metadata value. Previously, missing values defaulted to "no value" (#210)
-* Add/improve rkt, Docker, Kubernetes, and binary/systemd deployment docs
-* Add DialTimeout to gRPC client config (#273)
-* Allow query parameters to be used as template variables as `{{.request.query.foo}}` (#182)
-* Support nested metadata in responses from the "env file" style metadata endpoint (#84)
+* Templating:
+    * Allow query parameters to be used as template variables as `{{.request.query.foo}}` (#182)
+    * Support nested maps in responses from the "env file" metadata endpoint (#84)
+    * Error when a template is rendered with variables which are missing a referenced key. Previously, missing lookups defaulted to "no value" (#210)
+* gRPC API
+    * Add DialTimeout to gRPC client config (#273)
+    * Add IgnitionPut and Close to the client (#160,#193)
 
 #### Changes
 
-* Replace Ignition YAML templates with Fuze templates (**breaking**)
+* gRPC API requires TLS client authentication
+* Replace Ignition YAML templates with Fuze templates
     - Fuze formalizes the transform from Fuze configs (YAML) to Ignition 2.0.0 (JSON)
-    - [Migrate from bootcfg v0.3.0](Documentation/ignition.md#migration-from-v030)
+    - [Migrate templates from v0.3.0](Documentation/ignition.md#migration-from-v030)
     - Require CoreOS 1010.1.0 or newer
     - Drop support for Ignition v1 format
-* Replace template variable `{{.query}}` with `{{.request.raw_query}}` (**breaking**)
+* Replace template variable `{{.query}}` with `{{.request.raw_query}}`
 
 #### Examples
 
 * Kubernetes
-    * Upgrade Kubernetes (static manifest) examples to v1.3.0
-    * Add Kubernetes (self-hosted) example (PXE boot or install to disk)
-    * Mount /etc/resolv.conf into host kubelet for skydns and pod lookups (#237,#260)
+    * Upgrade Kubernetes v1.3.0 (static manifest) example clusters
+    * Add Kubernetes v1.3.0-beta.2 (self-hosted) example cluster
+    * Mount /etc/resolv.conf into host kubelet for skydns and pod DNS lookups (#237,#260)
     * Fix a bug in the k8s example k8s-certs@.service file check (#156)
-    * Avoid systemd dependency failures and restart components (#257,#274)
-* Add CoreOS Torus distributed storage cluster example (PXE boot)
+    * Avoid systemd dependency failures by restarting components (#257,#274)
+    * Verify Kubernetes v1.2.4 and v1.3.0 clusters pass conformance tests (#71,#265)
+* Add Torus distributed storage cluster example (PXE boot)
 * Add `create-uefi` subcommand to `scripts/libvirt` for UEFI/GRUB testing
-* Show CoreOS install to disk from a cached copy via bootcfg baseurl (#228)
+* Install CoreOS to disk from a cached copy via bootcfg baseurl (#228)
 * Remove 8.8.8.8 from networkd example Ignition configs (#184)
 * Match machines by MAC address in examples to simplify networkd device matching (#209)
 * With rkt 1.8+, you can use `rkt gc --grace-period=0` to cleanup rkt IP assignments in examples. The `rkt-gc-force` script has been removed.

diff --git a/Documentation/api.md b/Documentation/api.md
@@ -1,5 +1,5 @@
 
-# API
+# HTTP API
 
 ## iPXE Script
 
@@ -13,18 +13,21 @@ Serves a static iPXE boot script which gathers client machine attributes and cha
     #!ipxe
     chain ipxe?uuid=${uuid}&mac=${net0/mac:hexhyp}&domain=${domain}&hostname=${hostname}&serial=${serial}
 
+Client's booted with the `/ipxe.boot` endpoint will introspect and make a request to `/ipxe` with the `uuid`, `mac`, `hostname`, and `serial` value as query arguments.
+
 ## iPXE
 
 Finds the profile for the machine and renders the network boot config (kernel, options, initrd) as an iPXE script.
 
-    GET http://bootcfg.foo/ipxe
+    GET http://bootcfg.foo/ipxe?label=value
 
 **Query Parameters**
 
-| Name | Type   | Description   |
-|------|--------|---------------|
-| uuid | string | Hardware UUID |
-| mac  | string | MAC address   |
+| Name | Type   | Description     |
+|------|--------|-----------------|
+| uuid | string | Hardware UUID   |
+| mac  | string | MAC address     |
+| *    | string | Arbitrary label |
 
 **Response**
 
@@ -37,14 +40,15 @@ Finds the profile for the machine and renders the network boot config (kernel, o
 
 Finds the profile for the machine and renders the network boot config as a GRUB config. Use DHCP/TFTP to point GRUB clients to this endpoint as the next-server.
 
-    GET http://bootcfg.foo/grub
+    GET http://bootcfg.foo/grub?label=value
 
 **Query Parameters**
 
-| Name | Type   | Description   |
-|------|--------|---------------|
-| uuid | string | Hardware UUID |
-| mac  | string | MAC address   |
+| Name | Type   | Description     |
+|------|--------|-----------------|
+| uuid | string | Hardware UUID   |
+| mac  | string | MAC address     |
+| *    | string | Arbitrary label |
 
 **Response**
 
@@ -82,16 +86,17 @@ Finds the profile matching the machine and renders the network boot config as JS
 
 ## Cloud Config
 
-Finds the profile matching the machine and renders the corresponding Cloud-Config with metadata.
+Finds the profile matching the machine and renders the corresponding Cloud-Config with group metadata, selectors, and query params.
 
-    GET http://bootcfg.foo/cloud
+    GET http://bootcfg.foo/cloud?label=value
 
 **Query Parameters**
 
-| Name | Type   | Description   |
-|------|--------|---------------|
-| uuid | string | Hardware UUID |
-| mac  | string | MAC address   |
+| Name | Type   | Description     |
+|------|--------|-----------------|
+| uuid | string | Hardware UUID   |
+| mac  | string | MAC address     |
+| *    | string | Arbitrary label |
 
 **Response**
 
@@ -105,47 +110,44 @@ Finds the profile matching the machine and renders the corresponding Cloud-Confi
 
 ## Ignition Config
 
-Finds the profile matching the machine and renders the corresponding Ignition Config with metadata.
+Finds the profile matching the machine and renders the corresponding Ignition Config with group metadata, selectors, and query params.
 
-    GET http://bootcfg.foo/ignition
+    GET http://bootcfg.foo/ignition?label=value
 
 **Query Parameters**
 
-| Name | Type   | Description   |
-|------|--------|---------------|
-| uuid | string | Hardware UUID |
-| mac  | string | MAC address   |
+| Name | Type   | Description     |
+|------|--------|-----------------|
+| uuid | string | Hardware UUID   |
+| mac  | string | MAC address     |
+| *    | string | Arbitrary label |
 
 **Response**
 
     {
-      "ignitionVersion": 1,
-      "storage": {},
+      "ignition": { "version": "2.0.0" },
       "systemd": {
-        "units": [
-          {
-            "name": "hello.service",
-            "enable": true,
-            "contents": "[Service]\nType=oneshot\nExecStart=\/usr\/bin\/echo Hello World\n\n[Install]\nWantedBy=multi-user.target"
-          }
-        ]
-      },
-      "networkd": {},
-      "passwd": {}
+        "units": [{
+          "name": "example.service",
+          "enable": true,
+          "contents": "[Service]\nType=oneshot\nExecStart=/usr/bin/echo Hello World\n\n[Install]\nWantedBy=multi-user.target"
+        }]
+      }
     }
 
 ## Generic Config
 
-Finds the profile matching the machine and renders the corresponding Generic config with metadata and group selectors.
+Finds the profile matching the machine and renders the corresponding generic config with group metadata, selectors, and query params.
 
-    GET http://bootcfg.foo/generic
+    GET http://bootcfg.foo/generic?label=value
 
 **Query Parameters**
 
-| Name | Type   | Description   |
-|------|--------|---------------|
-| uuid | string | Hardware UUID |
-| mac  | string | MAC address   |
+| Name | Type   | Description     |
+|------|--------|-----------------|
+| uuid | string | Hardware UUID   |
+| mac  | string | MAC address     |
+| *    | string | Arbitrary label |
 
 **Response**
 
@@ -159,28 +161,29 @@ Finds the profile matching the machine and renders the corresponding Generic con
 
 ## Metadata
 
-Finds the matching machine group and renders the selectors and metadata as a `plain/text` file.
+Finds the matching machine group and renders the group metadata, selectors, and query params in an "env file" style response.
 
-    GET http://bootcfg.foo/metadata
+    GET http://bootcfg.foo/metadata?mac=52-54-00-a1-9c-ae&foo=bar&count=3&gate=true
 
 **Query Parameters**
 
-| Name | Type   | Description   |
-|------|--------|---------------|
-| uuid | string | Hardware UUID |
-| mac  | string | MAC address   |
+| Name | Type   | Description     |
+|------|--------|-----------------|
+| uuid | string | Hardware UUID   |
+| mac  | string | MAC address     |
+| *    | string | Arbitrary label |
 
 **Response**
 
-    IPV4_ADDRESS=172.15.0.21
-    NETWORKD_ADDRESS=172.15.0.21/16
-    NETWORKD_GATEWAY=172.15.0.1
-    NETWORKD_NAME=ens3
+    META=data
     ETCD_NAME=node1
-    FLEET_METADATA=role=etcd,name=node1
+    SOME_NESTED_DATA=some-value
     MAC=52:54:00:a1:9c:ae
-    ETCD_INITIAL_CLUSTER=node1=http://172.15.0.21:2380,node2=http://172.15.0.22:2380,node3=http://172.15.0.23:2380
-    NETWORKD_DNS=172.15.0.3
+    REQUEST_QUERY_MAC=52:54:00:a1:9c:ae
+    REQUEST_QUERY_FOO=bar
+    REQUEST_QUERY_COUNT=3
+    REQUEST_QUERY_GATE=true
+    REQUEST_RAW_QUERY=mac=52-54-00-a1-9c-ae&foo=bar&count=3&gate=true
 
 ## OpenPGP Signatures
 
@@ -193,6 +196,7 @@ OpenPGPG signature endpoints serve detached binary and ASCII armored signatures
 | GRUB2      | `http://bootcf.foo/grub.sig` | `http://bootcfg.foo/grub.asc` |
 | Ignition   | `http://bootcfg.foo/ignition.sig` | `http://bootcfg.foo/ignition.asc` |
 | Cloud-Config | `http://bootcfg.foo/cloud.sig` | `http://bootcfg.foo/cloud.asc` |
+| Generic    | `http://bootcfg.foo/generic.sig` | `http://bootcfg.foo/generic.asc` |
 | Metadata   | `http://bootcfg.foo/metadata.sig` | `http://bootcfg.foo/metadata.asc` |
 
 Get a config and its detached ASCII armored signature.