Add docs #3

ajeddeloh · 2019-07-08T23:01:34Z

arithx

Initial pass

arithx · 2019-07-09T17:15:07Z

README.md

  main, non-exported code

-base/
+`base/`
  Contains distro-agnostic code. Each package here targets only one Ignition
  spec verions.


s,verions,version,g

arithx · 2019-07-09T17:16:21Z

README.md

@@ -15,27 +20,27 @@ versions of the base and distro components that compose it. However a major
 or minor bump of either component necesitates a corresponding bump in the fcos
 config version.

-internal/
+`internal/`


It seems that changing these from bullets has removed the line-break + tab on the descriptions.

While that wasn't intentional, I think I'm ok with how it renders.

arithx · 2019-07-09T17:18:38Z

docs/examples.md

+        - key1
+```
+
+This example modifies the existing `core` user, giving it a known password hash (this will enable login via password), and setting its ssh key.


The Ignition docs have the description of the example above the example, should we follow that pattern?

arithx · 2019-07-09T17:19:16Z

docs/examples.md

+        - key3
+```
+
+This example will create two users, `user1` and `user2`. The first user has a password set and two ssh public keys authorized to log in as the user. The second user doesn't have a password set (so log in via password will be disabled), but have one ssh key.


s,but have one ssh key,but has one ssh key,g

arithx · 2019-07-09T17:20:09Z

docs/examples.md

+        - key3
+```
+
+This example will create two users, `user1` and `user2`. The first user has a password set and two ssh public keys authorized to log in as the user. The second user doesn't have a password set (so log in via password will be disabled), but have one ssh key.


Might read better to use the actual usernames instead of first user or second user.

arithx · 2019-07-09T17:25:52Z

docs/getting-started.md

@@ -0,0 +1,37 @@
+# Getting started
+
+fcct is a tool that will consume a Fedora CoreOS Config and produce a JSON file that can be given to a Fedora CoreOS machine when it first boots to set the machine up. Using this config, a machine can be told to create users, create filesystems, set up the network, install systemd units, and more.


Maybe configure the machine instead of set the machine up?

arithx · 2019-07-09T17:27:33Z

docs/getting-started.md

+
+To see some examples for what else ct can do, head over to the [examples][3].
+
+[1]: configuration-v1_0.md


Minor: use named anchors over numbered ones for ease of maintenance later on when potentially referencing the same section

arithx · 2019-07-09T17:27:59Z

docs/getting-started.md

+
+Fedora CoreOS Configs are YAML files conforming to fcct's schema. For more information on the schema, take a look at [doc/configuration-v1_0.md][1].
+
+As a simple example, let's use ct to set the authorized ssh key for the core user on a Fedora CoreOS machine.


s,ct,fcct,g

arithx · 2019-07-09T17:29:21Z

docs/getting-started.md

+{"ignition":{"config":{"replace":{"source":null,"verification":{}}},"security":{"tls":{}},"timeouts":{},"version":"3.0.0"},"passwd":{"users":[{"name":"core","sshAuthorizedKeys":["ssh-rsa ssh-rsa AAAAB3NzaC1yc..."]}]},"storage":{},"systemd":{}}
+```
+
+We can see that it produces a JSON file. This file isn't intended to be human-friendly, and will definitely be a pain to read/edit (especially if you have multi-line things like systemd units). Luckily, you shouldn't have to care about this file! Just provide it to a booting Fedora CoreOS machine and Ignition, the utility inside of Fedora CoreOS that receives this file, will know what to do with it.


Worth turning Ignition into a link to the repo?

arithx · 2019-07-09T17:29:46Z

docs/getting-started.md

+
+The method by which this file is provided to a Fedora CoreOS machine depends on the environment in which the machine is running. For instructions on a given provider, head over to the [list of supported platforms for Ignition][2].
+
+To see some examples for what else ct can do, head over to the [examples][3].


s,ct,fcct,g

bgilbert · 2019-07-10T00:00:51Z

docs/configuration-v1_0.md

+The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
+
+* **variant** (string): must be `fcos`
+* **version** (string): the sematic version of the spec for this document. This document is for version `1.0.0` and generates Ignition configs with version `3.0.0`.


bgilbert · 2019-07-10T00:01:06Z

docs/configuration-v1_0.md

+
+The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
+
+* **variant** (string): must be `fcos`


Trailing period for consistency

bgilbert · 2019-07-10T00:07:53Z

docs/getting-started.md

+
+Fedora CoreOS Configs are YAML files conforming to `fcct`'s schema. For more information on the schema, take a look at [doc/configuration-v1_0.md][spec].
+
+As a simple example, let's use `fcct` to set the authorized ssh key for the core user on a Fedora CoreOS machine.


core user

bgilbert · 2019-07-10T00:08:21Z

docs/getting-started.md

+
+As a simple example, let's use `fcct` to set the authorized ssh key for the core user on a Fedora CoreOS machine.
+
+```yaml


yaml fedora-coreos-config

bgilbert · 2019-07-10T00:11:21Z

docs/getting-started.md

+
+In this above file, you'll want to set the `ssh-rsa AAAAB3NzaC1yc...` line to be your ssh public key (which is probably the contents of `~/.ssh/id_rsa.pub`, if you're on Linux).
+
+If we take this file and give it to `fcct`:


Should we start by explaining how to download it?

bgilbert · 2019-07-10T00:14:42Z

docs/getting-started.md

+
+The method by which this file is provided to a Fedora CoreOS machine depends on the environment in which the machine is running. For instructions on a given provider, head over to the [list of supported platforms for Ignition][supported-platforms].
+
+To see some examples for what else `ct` can do, head over to the [examples][examples].


bgilbert · 2019-07-10T00:15:08Z

docs/examples.md

@@ -0,0 +1,184 @@
+# Examples
+
+Here you can find a bunch of simple examples for using fcct, with some explanations about what they do. The examples here are in no way comprehensive, for a full list of all the options present in ct check out the [configuration specification][spec].


present in fcct

bgilbert · 2019-07-10T00:16:02Z

docs/examples.md

+        - key1
+```
+
+This example will create two users, `user1` and `user2`. The `user1` has a password set and two ssh public keys authorized to log in as the user. `user2` doesn't have a password set (so log in via password will be disabled), but has one ssh key.


login via password

bgilbert · 2019-07-10T00:16:58Z

docs/examples.md

+
+## Users and groups
+
+This example modifies the existing `core` user, giving it a known password hash (this will enable login via password), and setting its ssh key.


We're disabling password auth by default (coreos/fedora-coreos-tracker#138) so these won't actually work.

bgilbert · 2019-07-10T00:18:11Z

docs/examples.md

+version: 1.0.0
+systemd:
+  units:
+    - name: etcd-member.service


Let's use a service we ship in the OS.

ajeddeloh · 2019-07-10T18:36:59Z

Fixed, added blurb on downloading/verifying fcct (although there's no releases to download yet), dropped everything related to password login, and swapped the example dropin to something useful (autologin on ttyS0)

bgilbert · 2019-07-10T18:43:38Z

docs/getting-started.md

@@ -0,0 +1,50 @@
+# Getting started
+
+`fcct`, the Fedora CoreOS Config Transpiler is a tool that consumes a Fedora CoreOS Config and produces an Ignition config, which is a JSON document that can be given to a Fedora CoreOS machine when it first boots. Using this config, a machine can be told to create users, create filesystems, set up the network, install systemd units, and more.


Transpiler,

bgilbert · 2019-07-10T19:00:43Z

docs/examples.md

+        - name: autologin.conf
+          contents: |
+            [Service]
+	    TTYVTDisallocate=no


Bad indentation.

This is just the Ignition doc with irrelevant bits removed and version and variant added.

This is mostly copied from the CL getting started guide.

Add some example fcc files

Add an explainer blurb that points to better docs, convert to markdown.

ajeddeloh · 2019-07-10T19:56:03Z

Fixed

bgilbert

LGTM

ajeddeloh force-pushed the add-docs branch 3 times, most recently from bc3e595 to d370c83 Compare July 8, 2019 23:22

arithx reviewed Jul 9, 2019

View reviewed changes

ajeddeloh force-pushed the add-docs branch from d370c83 to c73b994 Compare July 9, 2019 20:04

bgilbert reviewed Jul 10, 2019

View reviewed changes

ajeddeloh force-pushed the add-docs branch from c73b994 to 1317a04 Compare July 10, 2019 18:35

bgilbert reviewed Jul 10, 2019

View reviewed changes

Andrew Jeddeloh added 4 commits July 10, 2019 12:53

docs: add doc describing schema

418beba

This is just the Ignition doc with irrelevant bits removed and version and variant added.

docs: add getting started guide

3edba66

This is mostly copied from the CL getting started guide.

docs: add examples

0413321

Add some example fcc files

README: update readme to link to getting started

dd84656

Add an explainer blurb that points to better docs, convert to markdown.

ajeddeloh force-pushed the add-docs branch from 1317a04 to dd84656 Compare July 10, 2019 19:56

bgilbert approved these changes Jul 10, 2019

View reviewed changes

ajeddeloh merged commit 0e3ecf0 into master Jul 10, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs #3

Add docs #3

ajeddeloh commented Jul 8, 2019

arithx left a comment

arithx Jul 9, 2019

arithx Jul 9, 2019

ajeddeloh Jul 9, 2019

arithx Jul 9, 2019

arithx Jul 9, 2019

arithx Jul 9, 2019

arithx Jul 9, 2019

arithx Jul 9, 2019

arithx Jul 9, 2019

arithx Jul 9, 2019

arithx Jul 9, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

ajeddeloh commented Jul 10, 2019

bgilbert Jul 10, 2019

bgilbert Jul 10, 2019

ajeddeloh commented Jul 10, 2019

bgilbert left a comment

		@@ -0,0 +1,37 @@
		# Getting started

		fcct is a tool that will consume a Fedora CoreOS Config and produce a JSON file that can be given to a Fedora CoreOS machine when it first boots to set the machine up. Using this config, a machine can be told to create users, create filesystems, set up the network, install systemd units, and more.


		To see some examples for what else ct can do, head over to the [examples][3].

		[1]: configuration-v1_0.md


		Fedora CoreOS Configs are YAML files conforming to fcct's schema. For more information on the schema, take a look at [doc/configuration-v1_0.md][1].

		As a simple example, let's use ct to set the authorized ssh key for the core user on a Fedora CoreOS machine.


		The method by which this file is provided to a Fedora CoreOS machine depends on the environment in which the machine is running. For instructions on a given provider, head over to the [list of supported platforms for Ignition][2].

		To see some examples for what else ct can do, head over to the [examples][3].


		The Fedora CoreOS configuration is a YAML document conforming to the following specification, with _italicized_ entries being optional:

		* variant (string): must be `fcos`


		Fedora CoreOS Configs are YAML files conforming to `fcct`'s schema. For more information on the schema, take a look at [doc/configuration-v1_0.md][spec].

		As a simple example, let's use `fcct` to set the authorized ssh key for the core user on a Fedora CoreOS machine.


		As a simple example, let's use `fcct` to set the authorized ssh key for the core user on a Fedora CoreOS machine.

		```yaml


		In this above file, you'll want to set the `ssh-rsa AAAAB3NzaC1yc...` line to be your ssh public key (which is probably the contents of `~/.ssh/id_rsa.pub`, if you're on Linux).

		If we take this file and give it to `fcct`:


		The method by which this file is provided to a Fedora CoreOS machine depends on the environment in which the machine is running. For instructions on a given provider, head over to the [list of supported platforms for Ignition][supported-platforms].

		To see some examples for what else `ct` can do, head over to the [examples][examples].

		@@ -0,0 +1,184 @@
		# Examples

		Here you can find a bunch of simple examples for using fcct, with some explanations about what they do. The examples here are in no way comprehensive, for a full list of all the options present in ct check out the [configuration specification][spec].


		## Users and groups

		This example modifies the existing `core` user, giving it a known password hash (this will enable login via password), and setting its ssh key.

		@@ -0,0 +1,50 @@
		# Getting started

		`fcct`, the Fedora CoreOS Config Transpiler is a tool that consumes a Fedora CoreOS Config and produces an Ignition config, which is a JSON document that can be given to a Fedora CoreOS machine when it first boots. Using this config, a machine can be told to create users, create filesystems, set up the network, install systemd units, and more.

Add docs #3

Add docs #3

Conversation

ajeddeloh commented Jul 8, 2019

arithx left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ajeddeloh commented Jul 10, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ajeddeloh commented Jul 10, 2019

bgilbert left a comment

Choose a reason for hiding this comment