Add Fedora Atomic announcement and improve docs

poseidon · Apr 26, 2018 · 2e4bf4d · 2e4bf4d
1 parent b6a51d0
commit 2e4bf4d
Show file tree

Hide file tree

Showing 17 changed files with 88 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -24,18 +24,18 @@ Typhoon provides a Terraform Module for each supported operating system and plat
 | Platform      | Operating System | Terraform Module | Status |
 |---------------|------------------|------------------|--------|
 | AWS           | Container Linux  | [aws/container-linux/kubernetes](aws/container-linux/kubernetes) | stable |
-| AWS           | Fedora Atomic  | [aws/fedora-atomic/kubernetes](aws/fedora-atomic/kubernetes) | alpha |
+| AWS           | Fedora Atomic    | [aws/fedora-atomic/kubernetes](aws/fedora-atomic/kubernetes) | alpha |
 | Bare-Metal    | Container Linux  | [bare-metal/container-linux/kubernetes](bare-metal/container-linux/kubernetes) | stable |
-| Bare-Metal    | Fedora Atomic  | [bare-metal/fedora-atomic/kubernetes](bare-metal/fedora-atomic/kubernetes) | alpha |
+| Bare-Metal    | Fedora Atomic    | [bare-metal/fedora-atomic/kubernetes](bare-metal/fedora-atomic/kubernetes) | alpha |
 | Digital Ocean | Container Linux  | [digital-ocean/container-linux/kubernetes](digital-ocean/container-linux/kubernetes) | beta |
-| Digital Ocean | Fedora Atomic  | [digital-ocean/fedora-atomic/kubernetes](digital-ocean/fedora-atomic/kubernetes) | alpha |
+| Digital Ocean | Fedora Atomic    | [digital-ocean/fedora-atomic/kubernetes](digital-ocean/fedora-atomic/kubernetes) | alpha |
 | Google Cloud  | Container Linux  | [google-cloud/container-linux/kubernetes](google-cloud/container-linux/kubernetes) | beta |
-| Google Cloud  | Fedora Atomic  | [google-cloud/fedora-atomic/kubernetes](google-cloud/fedora-atomic/kubernetes) | very alpha |
+| Google Cloud  | Fedora Atomic    | [google-cloud/fedora-atomic/kubernetes](google-cloud/fedora-atomic/kubernetes) | very alpha |
 
 ## Documentation
 
 * [Docs](https://typhoon.psdn.io)
-* [Concepts](https://typhoon.psdn.io/concepts/)
+* Architecture [concepts](https://typhoon.psdn.io/architecture/concepts/) and [operating systems](https://typhoon.psdn.io/architecture/operating-systems/)
 * Tutorials for [AWS](https://typhoon.psdn.io/cl/aws/), [Bare-Metal](https://typhoon.psdn.io/cl/bare-metal/), [Digital Ocean](https://typhoon.psdn.io/cl/digital-ocean/), and [Google-Cloud](https://typhoon.psdn.io/cl/google-cloud/)
 
 ## Usage

diff --git a/docs/advanced/customization.md b/docs/advanced/customization.md
@@ -1,6 +1,6 @@
 # Customization
 
-Typhoon provides minimal Kubernetes clusters with defaults we recommend for production. Terraform variables provide easy to use and supported customizations for clusters. Advanced options are available for customizing the architecture or hosts.
+Typhoon provides Kubernetes clusters with defaults recommended for production. Terraform variables expose supported customization options. Advanced options are available for customizing the architecture or hosts as well.
 
 ## Variables
 
@@ -115,9 +115,13 @@ Container Linux Configs (and the CoreOS Ignition system) create immutable infras
 !!! danger
     Destroying and recreating controller instances is destructive! etcd runs on controller instances and stores data there. Do not modify controller snippets. See [blue/green](https://typhoon.psdn.io/topics/maintenance/#upgrades) clusters.
 
+### Fedora Atomic
+
+Cloud-Init and kickstart (bare-metal only) declare how a Fedora Atomic instance should be provisioned. Customizing these declarations in ways beyond the provided Terraform variables is unsupported.
+
 ## Architecture
 
-To customize clusters in ways that aren't supported by input variables, fork Typhoon and maintain a repository with customizations. Reference the repository by changing the username.
+Typhoon chooses variables to expose with purpose. If you must customize clusters in ways that aren't supported by input variables, fork Typhoon and maintain a repository with customizations. Reference the repository by changing the username.
 
 ```
 module "digital-ocean-nemo" {

diff --git a/docs/advanced/worker-pools.md b/docs/advanced/worker-pools.md
@@ -5,7 +5,9 @@ Typhoon AWS and Google Cloud allow additional groups of workers to be defined an
 Internal Terraform Modules:
 
 * `aws/container-linux/kubernetes/workers`
+* `aws/fedora-atomic/kubernetes/workers`
 * `google-cloud/container-linux/kubernetes/workers`
+* `google-cloud/fedora-atomic/kubernetes/workers`
 
 ## AWS
 

diff --git a/docs/announce.md b/docs/announce.md
@@ -0,0 +1,34 @@
+# Announce <img align="right" src="https://storage.googleapis.com/poseidon/typhoon-logo-small.png">
+
+## April 26, 2018
+
+Introducing Typhoon Kubernetes clusters for Fedora Atomic!
+
+Fedora Atomic is a container-optimized operating system designed for large-scale custered operation, immutable infrastructure, and atomic operating system upgrades. [Fedora Atomic](https://getfedora.org/en/atomic/download/) is part of [Project Atomic](http://www.projectatomic.io/docs/introduction/), a Red Hat sponsored project working on rpm-ostree, buildah, skopeo, CRI-O, and the related CentOS/RHEL Atomic.
+
+For newcomers, Typhoon is a free (cost and freedom) Kubernetes distribution providing upstream Kubernetes, declarative configuration via [Terraform](https://www.terraform.io/intro/index.html), and support for AWS, Google Cloud, DigitalOcean, and bare-metal. Typhoon clusters use a [self-hosted](https://github.com/kubernetes-incubator/bootkube) control plane, support [Calico](https://www.projectcalico.org/blog/) and [flannel](https://coreos.com/flannel/docs/latest/) CNI networking, and enable etcd TLS, [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/), and network policy.
+
+Typhoon for Fedora Atomic reflects many of the same principles that created Typhoon for Container Linux. Clusters are declared using plain Terraform configs that can be versioned. In lieu of Ignition, instances are declaratively provisioned with Cloud-Init and kickstart (bare-metal only). TLS assets are generated. Hosts run only a kubelet service, other components are scheduled (i.e. self-hosted). The upstream hyperkube is used directly[^1]. And clusters are kept minimal by offering optional addons for [Ingress](https://typhoon.psdn.io/addons/ingress/), [Prometheus](https://typhoon.psdn.io/addons/prometheus/), and [Grafana](https://typhoon.psdn.io/addons/grafana/). Typhoon compliments and enhances Fedora Atomic as a choice of operating system for Kubernetes.
+
+Meanwhile, Fedora Atomic adds some promising new low-level technologies:
+
+* [ostree](https://github.com/ostreedev/ostree) & [rpm-ostree](https://github.com/projectatomic/rpm-ostree) - a hybrid, layered, image and package system that lets you perform atomic updates and rollbacks, layer on packages, "rebase" your system, or manage a remote tree repo. See Dusty Mabe's great [intro](https://dustymabe.com/2017/09/01/atomic-host-101-lab-part-3-rebase-upgrade-rollback/). 
+
+* [system containers](http://www.projectatomic.io/blog/2016/09/intro-to-system-containers/) - OCI container images that embed systemd and runc metadata for starting low-level host services before container runtimes are ready. Typhoon uses system containers under runc for `etcd`, `kubelet`, and `bootkube` on Fedora Atomic (instead of rkt-fly).
+
+* [CRI-O](https://github.com/kubernetes-incubator/cri-o) - CRI-O is a kubernetes-incubator implementation of the Kubernetes Container Runtime Interface. Typhoon uses Docker as the container runtime today, but its a goal to gradually introduce CRI-O as an alternative runtime as it matures.
+
+Typhoon has long [aspired](https://github.com/poseidon/typhoon/blob/2faacc6a50993038c98789dfa96430a757bdf545/docs/faq.md#operating-systems) to add a dissimilar operating system to compliment Container Linux. Operating Typhoon clusters across colocations and multiple clouds was driven by real need and has provided healthy perspective and clear direction. Fedora Atomic is an exciting addition because its similarly driven by need and should be healthy for Typhoon. Fedora Atomic diversifies Typhoon's technology underpinnings, uniting the Container Linux and Fedora Atomic ecosystems to provide a consistent Kubernetes experience across operating systems, clouds, and on-premise.
+
+Get started with the [basics](https://typhoon.psdn.io/architecture/concepts/) or read the OS [comparison](https://typhoon.psdn.io/architecture/operating-systems/). If you're familiar with Terraform, follow the new tutorials for Fedora Atomic on [AWS](https://typhoon.psdn.io/atomic/aws/), [Google Cloud](https://typhoon.psdn.io/atomic/google-cloud/), [DigitalOcean](https://typhoon.psdn.io/atomic/digital-ocean/), and [bare-metal](https://typhoon.psdn.io/atomic/bare-metal/).
+
+*Typhoon is not affiliated with Red Hat or Project Atomic.*
+
+!!! warning
+    Heed the warnings. Typhoon for Fedora Atomic is still alpha. Container Linux continues to be the recommended flavor for production clusters. Atomic is not meant to detract from efforts on Container Linux or its derivatives.
+
+!!! tip
+    For bare-metal, you may continue to use your v0.7+ [Matchbox](https://github.com/coreos/matchbox) service and `terraform-provider-matchbox` plugin to provision both Container Linux and Fedora Atomic clusters. No changes needed.
+
+[^1]: Using `etcd`, `kubelet`, and `bootkube` as system containers required metadata files be added in [system-containers](https://github.com/poseidon/system-containers)
+
diff --git a/docs/concepts.md → docs/architecture/concepts.md b/docs/concepts.md → docs/architecture/concepts.md
diff --git a/docs/architecture/operating-systems.md b/docs/architecture/operating-systems.md
@@ -10,28 +10,36 @@ Typhoon supports [Container Linux](https://coreos.com/why/) and Fedora [Atomic](
 Together, they diversify Typhoon to support a range of container technologies.
 
 * Container Linux: Gentoo core, rkt-fly, docker
-* Fedora Atomic: RHEL core, rpm-ostree, system containers (i.e. runc), CRI-O
+* Fedora Atomic: RHEL core, rpm-ostree, system containers (i.e. runc), CRI-O (future)
 
-## Kubernetes
+## Host Properties
 
 | Property          | Container Linux | Fedora Atomic |
 |-------------------|-----------------|---------------|
-| control plane     | self-hosted | self-hosted |
-| kubelet image     | upstream hyperkube | upstream hyperkube in system container |
-| controller images | upstream hyperkube | upstream hyperkube |
-| on-host etcd      | rkt-fly   | system container (runc) |
-| on-host kubelet   | rkt-fly   | system container (runc) |
-| host spec (bare-metal) | Container Linux Config | kickstart, cloud-init | 
+| host spec (bare-metal) | Container Linux Config | kickstart, cloud-init |
 | host spec (cloud)      | Container Linux Config | cloud-init |
-| CNI plugins       | calico or flannel | calico or flannel |
-| container runtime | docker    | docker (CRIO soon) |
+| container runtime | docker    | docker (CRIO planned) |
 | cgroup driver     | cgroupfs  | systemd  |
 | logging driver    | json-file | journald |
 | storage driver    | overlay2  | overlay2 |
 
-## Locations
+## Kubernetes Properties
+
+| Property          | Container Linux | Fedora Atomic |
+|-------------------|-----------------|---------------|
+| single-master     | all platforms | all platforms |
+| multi-master      | all platforms | all platforms |
+| control plane     | self-hosted   | self-hosted   |
+| kubelet image     | upstream hyperkube | upstream hyperkube via [system container](https://github.com/poseidon/system-containers) |
+| control plane images | upstream hyperkube | upstream hyperkube |
+| on-host etcd      | rkt-fly   | system container (runc) |
+| on-host kubelet   | rkt-fly   | system container (runc) |
+| CNI plugins       | calico or flannel | calico or flannel |
+| coordinated drain & OS update | [CLUO](https://github.com/coreos/container-linux-update-operator) addon | manual (planned) |
+
+## Directory Locations
 
-Typhoon standard locations.
+Typhoon conventional directories.
 
 | Kubelet setting   | Host location                  |
 |-------------------|--------------------------------|
@@ -77,5 +85,5 @@ Typhoon standard locations.
 | /lib/modules       | /lib/modules     | ro |
 | /etc/hosts         | /etc/hosts       | ro |
 | /etc/resolv.conf   | /etc/resolv.conf | ro |
-| /opt/cni/bin       | /opt/cni/bin     | |
+| /opt/cni/bin       | /opt/cni/bin (changing in future) | |
 
diff --git a/docs/atomic/aws.md b/docs/atomic/aws.md
@@ -24,7 +24,7 @@ $ terraform version
 Terraform v0.11.7
 ```
 
-Read [concepts](../concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
+Read [concepts](../architecture/concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
 
 ```
 cd infra/clusters
@@ -83,7 +83,7 @@ Define a Kubernetes cluster using the module `aws/fedora-atomic/kubernetes`.
 
 ```tf
 module "aws-tempest" {
-  source = "git::https://github.com/poseidon/typhoon//aws/fedora-atomic/kubernetes?ref=v1.10.1"
+  source = "git::https://github.com/poseidon/typhoon//aws/fedora-atomic/kubernetes?ref=v1.10.2"
 
   providers = {
     aws = "aws.default"

diff --git a/docs/atomic/bare-metal.md b/docs/atomic/bare-metal.md
@@ -189,7 +189,7 @@ providers {
 }
 ```
 
-Read [concepts](../concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
+Read [concepts](../architecture/concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
 
 ```
 cd infra/clusters
@@ -234,7 +234,7 @@ Define a Kubernetes cluster using the module `bare-metal/fedora-atomic/kubernete
 
 ```tf
 module "bare-metal-mercury" {
-  source = "git::https://github.com/poseidon/typhoon//bare-metal/fedora-atomic/kubernetes?ref=v1.10.1"
+  source = "git::https://github.com/poseidon/typhoon//bare-metal/fedora-atomic/kubernetes?ref=v1.10.2"
   
   providers = {
     local = "local.default"

diff --git a/docs/atomic/digital-ocean.md b/docs/atomic/digital-ocean.md
@@ -24,7 +24,7 @@ $ terraform version
 Terraform v0.11.7
 ```
 
-Read [concepts](../concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
+Read [concepts](../architecture/concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
 
 ```
 cd infra/clusters
@@ -77,7 +77,7 @@ Define a Kubernetes cluster using the module `digital-ocean/fedora-atomic/kubern
 
 ```tf
 module "digital-ocean-nemo" {
-  source = "git::https://github.com/poseidon/typhoon//digital-ocean/fedora-atomic/kubernetes?ref=v1.10.1"
+  source = "git::https://github.com/poseidon/typhoon//digital-ocean/fedora-atomic/kubernetes?ref=v1.10.2"
   
   providers = {
     digitalocean = "digitalocean.default"

diff --git a/docs/atomic/google-cloud.md b/docs/atomic/google-cloud.md
@@ -25,7 +25,7 @@ $ terraform version
 Terraform v0.11.7
 ```
 
-Read [concepts](../concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
+Read [concepts](../architecture/concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
 
 ```
 cd infra/clusters
@@ -119,7 +119,7 @@ Define a Kubernetes cluster using the module `google-cloud/fedora-atomic/kuberne
 
 ```tf
 module "google-cloud-yavin" {
-  source = "git::https://github.com/poseidon/typhoon//google-cloud/fedora-atomic/kubernetes?ref=v1.10.1"
+  source = "git::https://github.com/poseidon/typhoon//google-cloud/fedora-atomic/kubernetes?ref=v1.10.2"
   
   providers = {
     google   = "google.default"

diff --git a/docs/cl/aws.md b/docs/cl/aws.md
@@ -37,7 +37,7 @@ providers {
 }
 ```
 
-Read [concepts](../concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
+Read [concepts](../architecture/concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
 
 ```
 cd infra/clusters

diff --git a/docs/cl/bare-metal.md b/docs/cl/bare-metal.md
@@ -129,7 +129,7 @@ providers {
 }
 ```
 
-Read [concepts](../concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
+Read [concepts](../architecture/concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
 
 ```
 cd infra/clusters

diff --git a/docs/cl/digital-ocean.md b/docs/cl/digital-ocean.md
@@ -37,7 +37,7 @@ providers {
 }
 ```
 
-Read [concepts](../concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
+Read [concepts](../architecture/concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
 
 ```
 cd infra/clusters

diff --git a/docs/cl/google-cloud.md b/docs/cl/google-cloud.md
@@ -37,7 +37,7 @@ providers {
 }
 ```
 
-Read [concepts](../concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
+Read [concepts](../architecture/concepts.md) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`).
 
 ```
 cd infra/clusters

diff --git a/docs/index.md b/docs/index.md
@@ -16,7 +16,6 @@ Typhoon distributes upstream Kubernetes, architectural conventions, and cluster
 * On-cluster etcd with TLS, [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/)-enabled, [network policy](https://kubernetes.io/docs/concepts/services-networking/network-policies/)
 * Advanced features like [worker pools](https://typhoon.psdn.io/advanced/worker-pools/) and [preemption](https://typhoon.psdn.io/google-cloud/#preemption) (varies by platform)
 * Ready for Ingress, Prometheus, Grafana, and other optional [addons](https://typhoon.psdn.io/addons/overview/)
-* Provided via Terraform Modules
 
 ## Modules
 
@@ -27,15 +26,15 @@ Typhoon provides a Terraform Module for each supported operating system and plat
 | AWS           | Container Linux  | [aws/container-linux/kubernetes](cl/aws.md) | stable |
 | AWS           | Fedora Atomic    | [aws/fedora-atomic/kubernetes](atomic/aws.md) | alpha |
 | Bare-Metal    | Container Linux  | [bare-metal/container-linux/kubernetes](cl/bare-metal.md) | stable |
-| Bare-Metal    | Fedora Atomic  | [bare-metal/fedora-atomic/kubernetes](atomic/bare-metal.md) | alpha |
+| Bare-Metal    | Fedora Atomic    | [bare-metal/fedora-atomic/kubernetes](atomic/bare-metal.md) | alpha |
 | Digital Ocean | Container Linux  | [digital-ocean/container-linux/kubernetes](cl/digital-ocean.md) | beta |
-| Digital Ocean | Fedora Atomic  | [digital-ocean/fedora-atomic/kubernetes](atomic/digital-ocean.md) | alpha |
+| Digital Ocean | Fedora Atomic    | [digital-ocean/fedora-atomic/kubernetes](atomic/digital-ocean.md) | alpha |
 | Google Cloud  | Container Linux  | [google-cloud/container-linux/kubernetes](cl/google-cloud.md) | beta |
-| Google Cloud  | Fedora Atomic  | [google-cloud/container-linux/kubernetes](atomic/google-cloud.md) | very alpha |
+| Google Cloud  | Fedora Atomic    | [google-cloud/container-linux/kubernetes](atomic/google-cloud.md) | very alpha |
 
 ## Documentation
 
-* [Concepts](concepts.md)
+* Architecture [concepts](architecture/concepts.md) and [operating-systems](architecture/operating-systems.md)
 * Tutorials for [AWS](cl/aws.md), [Bare-Metal](cl/bare-metal.md), [Digital Ocean](cl/digital-ocean.md), and [Google-Cloud](cl/google-cloud.md)
 
 ## Example

diff --git a/docs/topics/hardware.md b/docs/topics/hardware.md
@@ -1,6 +1,6 @@
 # Hardware
 
-Typhoon ensures certain router and server hardware integrates well with bare-metal Kubernetes.
+Typhoon ensures certain networking hardware integrates well with bare-metal Kubernetes.
 
 ## Ubiquiti
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,7 +6,7 @@ repo_url: 'https://github.com/poseidon/typhoon'
 theme:
   name: 'material'
   feature:
-    tabs: true
+    tabs: 'true'
   palette:
     primary: 'blue'
     accent: 'pink'
@@ -44,8 +44,9 @@ markdown_extensions:
   - pymdownx.tilde
 pages:
   - Home: 'index.md'
+  - 'Announce': 'announce.md'
   - 'Architecture':
-    - 'Concepts': 'concepts.md'
+    - 'Concepts': 'architecture/concepts.md'
     - 'Operating Systems': 'architecture/operating-systems.md'
   - 'Container Linux': 
     - 'AWS': 'cl/aws.md'