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 17e7d4ed..fdfdfc30 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 55485d3d..47b8ac2a 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 486759cc..6c77dc82 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 00000000..4a47774d --- /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 b12d2579..c0e6db56 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 -Typhoon standard locations. +| 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 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 45a8c88f..916d2b99 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 a1a7ba4d..96338ba5 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 423b568b..0c186b53 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 4204a3cc..daaba077 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 f6211c3c..68e1ad09 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 c5f5f10b..815fee36 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 f4d299f3..7f3df5ff 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 b9d181bc..5765b8ba 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 f91bde57..dc907a24 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 e82bd6e6..518c2c7a 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 a46f5fc6..4e3b83cb 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'