From 2e4bf4d7ae73076c8ee0d53c26e3783489a76185 Mon Sep 17 00:00:00 2001 From: Dalton Hubble Date: Thu, 26 Apr 2018 02:41:04 -0700 Subject: [PATCH] Add Fedora Atomic announcement and improve docs --- README.md | 10 ++++---- docs/advanced/customization.md | 8 ++++-- docs/advanced/worker-pools.md | 2 ++ docs/announce.md | 34 ++++++++++++++++++++++++++ docs/{ => architecture}/concepts.md | 0 docs/architecture/operating-systems.md | 34 ++++++++++++++++---------- docs/atomic/aws.md | 4 +-- docs/atomic/bare-metal.md | 4 +-- docs/atomic/digital-ocean.md | 4 +-- docs/atomic/google-cloud.md | 4 +-- docs/cl/aws.md | 2 +- docs/cl/bare-metal.md | 2 +- docs/cl/digital-ocean.md | 2 +- docs/cl/google-cloud.md | 2 +- docs/index.md | 9 +++---- docs/topics/hardware.md | 2 +- mkdocs.yml | 5 ++-- 17 files changed, 88 insertions(+), 40 deletions(-) create mode 100644 docs/announce.md rename docs/{ => architecture}/concepts.md (100%) diff --git a/README.md b/README.md index 17e7d4ed9..fdfdfc300 100644 --- 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 index 55485d3d1..47b8ac2ae 100644 --- 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 index 486759cc0..6c77dc829 100644 --- 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 new file mode 100644 index 000000000..4a47774d2 --- /dev/null +++ b/docs/announce.md @@ -0,0 +1,34 @@ +# Announce + +## 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 b/docs/architecture/concepts.md similarity index 100% rename from docs/concepts.md rename to docs/architecture/concepts.md diff --git a/docs/architecture/operating-systems.md b/docs/architecture/operating-systems.md index b12d2579f..c0e6db566 100644 --- 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 index 45a8c88fa..916d2b997 100644 --- 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 index a1a7ba4dd..96338ba5e 100644 --- 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 index 423b568bd..0c186b53b 100644 --- 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 index 4204a3ccc..daaba0775 100644 --- 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 index f6211c3c9..68e1ad096 100644 --- 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 index c5f5f10b4..815fee369 100644 --- 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 index f4d299f31..7f3df5ff3 100644 --- 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 index b9d181bc3..5765b8ba2 100644 --- 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 index f91bde571..dc907a248 100644 --- 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 index e82bd6e64..518c2c7ac 100644 --- 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 index a46f5fc69..4e3b83cbf 100644 --- 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'