WIP docs: Migrate docs site from mkdocs-material to mdBook

Makefile

@@ -609,18 +609,11 @@ prow-postsubmit: version-dist
 
 .PHONY: live-docs
 live-docs:
-	docker build -t kops/mkdocs images/mkdocs
-	docker run --rm -it -p 3000:3000 -v ${PWD}:/docs kops/mkdocs
+	${KOPS_ROOT}/hack/build-mdbook.sh serve
 
 .PHONY: build-docs
 build-docs:
-	docker build --pull -t kops/mkdocs images/mkdocs
-	docker run --rm -v ${PWD}:/docs kops/mkdocs build
-
-.PHONY: build-docs-netlify
-build-docs-netlify:
-	pip install -r ${KOPS_ROOT}/images/mkdocs/requirements.txt
-	python -m mkdocs build
+	${KOPS_ROOT}/hack/build-mdbook.sh build
 
 #-----------------------------------------------------------
 # development targets

book.toml

@@ -0,0 +1,32 @@
+[book]
+title = "kOps - Kubernetes Operations"
+authors = ["The Kubernetes Authors"]
+description = "Production-grade Kubernetes cluster lifecycle management"
+src = "docs"
+language = "en"
+
+[build]
+build-dir = "site"
+
+[output.html]
+git-repository-url = "https://github.com/kubernetes/kops"
+edit-url-template = "https://github.com/kubernetes/kops/edit/master/docs/{path}"
+site-url = "/"
+default-theme = "light"
+preferred-dark-theme = "navy"
+no-section-label = true
+additional-css = ["docs/extra.css"]
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.search]
+enable = true
+limit-results = 30
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 1
+boost-paragraph = 1
+expand = true
+heading-split-level = 3

docs/SUMMARY.md

@@ -0,0 +1,243 @@
+# Summary
+
+[Welcome](index.md)
+
+# Welcome
+
+- [Releases & Versioning](welcome/releases.md)
+- [Office Hours](welcome/office_hours.md)
+- [Values](values.md)
+
+# Getting Started
+
+- [Installing](getting_started/install.md)
+- [Binary install](install.md)
+- [Deploying to AWS](getting_started/aws.md)
+- [Deploying to GCE](getting_started/gce.md)
+- [Deploying to Digital Ocean - Beta](getting_started/digitalocean.md)
+- [Deploying to Hetzner - Beta](getting_started/hetzner.md)
+- [Deploying to OpenStack - Beta](getting_started/openstack.md)
+- [Deploying to Azure - Alpha](getting_started/azure.md)
+- [Deploying to Scaleway - Alpha](getting_started/scaleway.md)
+- [Deploying to Spot Ocean - Alpha](getting_started/spot-ocean.md)
+- [kOps Commands](getting_started/commands.md)
+- [kOps Arguments](getting_started/arguments.md)
+- [kubectl usage](getting_started/kubectl.md)
+- [Production setup](getting_started/production.md)
+
+# CLI
+
+- [kops](cli/kops.md)
+- [kops completion](cli/kops_completion.md)
+  - [kops completion bash](cli/kops_completion_bash.md)
+  - [kops completion fish](cli/kops_completion_fish.md)
+  - [kops completion powershell](cli/kops_completion_powershell.md)
+  - [kops completion zsh](cli/kops_completion_zsh.md)
+- [kops create](cli/kops_create.md)
+  - [kops create cluster](cli/kops_create_cluster.md)
+  - [kops create instancegroup](cli/kops_create_instancegroup.md)
+  - [kops create keypair](cli/kops_create_keypair.md)
+  - [kops create secret](cli/kops_create_secret.md)
+    - [kops create secret ciliumpassword](cli/kops_create_secret_ciliumpassword.md)
+    - [kops create secret dockerconfig](cli/kops_create_secret_dockerconfig.md)
+    - [kops create secret encryptionconfig](cli/kops_create_secret_encryptionconfig.md)
+  - [kops create sshpublickey](cli/kops_create_sshpublickey.md)
+- [kops delete](cli/kops_delete.md)
+  - [kops delete cluster](cli/kops_delete_cluster.md)
+  - [kops delete instance](cli/kops_delete_instance.md)
+  - [kops delete instancegroup](cli/kops_delete_instancegroup.md)
+  - [kops delete secret](cli/kops_delete_secret.md)
+  - [kops delete sshpublickey](cli/kops_delete_sshpublickey.md)
+- [kops distrust](cli/kops_distrust.md)
+  - [kops distrust keypair](cli/kops_distrust_keypair.md)
+- [kops edit](cli/kops_edit.md)
+  - [kops edit cluster](cli/kops_edit_cluster.md)
+  - [kops edit instancegroup](cli/kops_edit_instancegroup.md)
+- [kops export](cli/kops_export.md)
+  - [kops export kubeconfig](cli/kops_export_kubeconfig.md)
+- [kops get](cli/kops_get.md)
+  - [kops get all](cli/kops_get_all.md)
+  - [kops get assets](cli/kops_get_assets.md)
+  - [kops get clusters](cli/kops_get_clusters.md)
+  - [kops get instancegroups](cli/kops_get_instancegroups.md)
+  - [kops get instances](cli/kops_get_instances.md)
+  - [kops get keypairs](cli/kops_get_keypairs.md)
+  - [kops get secrets](cli/kops_get_secrets.md)
+  - [kops get sshpublickeys](cli/kops_get_sshpublickeys.md)
+- [kops promote](cli/kops_promote.md)
+  - [kops promote keypair](cli/kops_promote_keypair.md)
+- [kops reconcile](cli/kops_reconcile.md)
+  - [kops reconcile cluster](cli/kops_reconcile_cluster.md)
+- [kops replace](cli/kops_replace.md)
+- [kops rolling-update](cli/kops_rolling-update.md)
+  - [kops rolling-update cluster](cli/kops_rolling-update_cluster.md)
+- [kops toolbox](cli/kops_toolbox.md)
+  - [kops toolbox addons](cli/kops_toolbox_addons.md)
+    - [kops toolbox addons apply](cli/kops_toolbox_addons_apply.md)
+    - [kops toolbox addons list](cli/kops_toolbox_addons_list.md)
+  - [kops toolbox clusterapi](cli/kops_toolbox_clusterapi.md)
+    - [kops toolbox clusterapi generate](cli/kops_toolbox_clusterapi_generate.md)
+      - [kops toolbox clusterapi generate machinedeployment](cli/kops_toolbox_clusterapi_generate_machinedeployment.md)
+  - [kops toolbox dump](cli/kops_toolbox_dump.md)
+  - [kops toolbox enroll](cli/kops_toolbox_enroll.md)
+  - [kops toolbox instance-selector](cli/kops_toolbox_instance-selector.md)
+  - [kops toolbox template](cli/kops_toolbox_template.md)
+- [kops trust](cli/kops_trust.md)
+  - [kops trust keypair](cli/kops_trust_keypair.md)
+- [kops update](cli/kops_update.md)
+  - [kops update cluster](cli/kops_update_cluster.md)
+- [kops upgrade](cli/kops_upgrade.md)
+  - [kops upgrade cluster](cli/kops_upgrade_cluster.md)
+- [kops validate](cli/kops_validate.md)
+  - [kops validate cluster](cli/kops_validate_cluster.md)
+- [kops version](cli/kops_version.md)
+
+# API
+
+- [Cluster Resource](cluster_spec.md)
+- [InstanceGroup Resource](instance_groups.md)
+- [Addon Objects](addon_objects.md)
+
+# Addons
+
+- [Addons](addons.md)
+
+# Operations
+
+- [Updates & Upgrades](operations/updates_and_upgrades.md)
+- [Rolling Updates](operations/rolling-update.md)
+- [Working with Instance Groups](tutorial/working-with-instancegroups.md)
+- [Upgrading Kubernetes](tutorial/upgrading-kubernetes.md)
+- [Using Manifests and Customizing](manifests_and_customizing_via_api.md)
+- [High Availability](operations/high_availability.md)
+- [Scaling](operations/scaling.md)
+- [Karpenter](operations/karpenter.md)
+- [Local asset repositories](operations/asset-repository.md)
+- [Instancegroup images](operations/images.md)
+- [Cluster configuration management](changing_configuration.md)
+- [Cluster Templating](operations/cluster_template.md)
+- [GPU setup](gpu.md)
+- [Label management](labels.md)
+- [Rotate Secrets](operations/rotate-secrets.md)
+- [Service Account Issuer Migration](operations/service_account_issuer_migration.md)
+- [Service Account Token Volume](operations/service_account_token_volumes.md)
+- [Moving from a Single Master to Multiple HA Masters](single-to-multi-master.md)
+- [Running kOps in a CI environment](continuous_integration.md)
+- [Gossip DNS](gossip.md)
+- [etcd administration](operations/etcd_administration.md)
+- [etcd backup, restore and encryption](operations/etcd_backup_restore_encryption.md)
+- [etcd3 Migration](etcd3-migration.md)
+- [Troubleshooting](operations/troubleshoot.md)
+- [E2E Failure Troubleshooting](e2e-failure-troubleshooting.md)
+
+# Networking
+
+- [Networking Overview](networking.md)
+- [AWS VPC](networking/aws-vpc.md)
+- [Calico](networking/calico.md)
+- [Cilium](networking/cilium.md)
+- [Flannel](networking/flannel.md)
+- [Kindnet](networking/kindnet.md)
+- [Kube-Router](networking/kube-router.md)
+- [IPv6](networking/ipv6.md)
+- [Run kOps in an existing VPC](run_in_existing_vpc.md)
+- [Supported network topologies](topology.md)
+- [Subdomain setup](creating_subdomain.md)
+
+# Security
+
+- [Security](security.md)
+- [Advisories](advisories/README.md)
+  - [CVE-2017-14491](advisories/cve_2017_14491.md)
+  - [CVE-2019-5736](advisories/cve_2019_5736.md)
+  - [etcd-manager certificate expiration](advisories/etcd-manager-certificate-expiration.md)
+  - [Spectre/Meltdown kernel update](advisories/spectre-meltdown-kernel-update.md)
+- [Bastion setup](bastion.md)
+- [Instance IAM roles](iam_roles.md)
+- [MFA setup](mfa.md)
+- [Security Groups](security_groups.md)
+
+# Advanced
+
+- [Download Config](advanced/download_config.md)
+- [Subdomain NS Records](advanced/ns.md)
+- [Experimental](advanced/experimental.md)
+- [Cluster boot sequence](boot-sequence.md)
+- [Philosophy](philosophy.md)
+- [State store](state.md)
+- [AWS China](aws-china.md)
+- [Custom CA](custom_ca.md)
+- [Horizontal Pod Autoscaling](horizontal_pod_autoscaling.md)
+- [Egress Proxy](http_proxy.md)
+- [Node Resource Allocation](node_resource_handling.md)
+- [Terraform](terraform.md)
+- [Authentication](authentication.md)
+- [Bare Metal](metal.md)
+- [OpenTelemetry](opentelemetry.md)
+- [kops-controller Architecture](architecture/kops-controller.md)
+
+# Contributing
+
+- [Getting Involved and Contributing](contributing/index.md)
+- [New Kubernetes Version](contributing/new_kubernetes_version.md)
+- [Our Release Process](contributing/release-process.md)
+- [Releasing With Homebrew](contributing/homebrew.md)
+- [Updating The Default Base AMI](contributing/update_ami_versions.md)
+- [Building](contributing/building.md)
+- [Adding a feature](contributing/adding_a_feature.md)
+- [Testing](contributing/testing.md)
+- [Testing preview versions](contributing/test_versions.md)
+- [Developing using Docker](contributing/Docker.md)
+- [Documentation Guidelines](contributing/documentation.md)
+- [Hack Directory](contributing/hack.md)
+- [How to update kOps API](contributing/api_updates.md)
+- [Low level description on how kOps works](contributing/how_it_works.md)
+- [Notes on Gossip design](contributing/gossip.md)
+- [Notes on master instance sizing](contributing/instancesizes.md)
+- [Vendoring](contributing/vendoring.md)
+- [Ports](contributing/ports.md)
+- [Cluster Addons & Manager](contributing/addons.md)
+- [Proposing a Cherry-Pick](contributing/proposing-a-cherry-pick.md)
+
+# Examples
+
+- [Examples Overview](examples/README.md)
+- [Basic Requirements](examples/basic-requirements.md)
+- [CoreOS Multi-master](examples/coreos-kops-tests-multimaster.md)
+- [Route53 Subdomain](examples/kops-test-route53-subdomain.md)
+- [Private Net with Bastion](examples/kops-tests-private-net-bastion-host.md)
+
+# Releases
+
+- [1.36](releases/1.36-NOTES.md)
+- [1.35](releases/1.35-NOTES.md)
+- [1.34](releases/1.34-NOTES.md)
+- [1.33](releases/1.33-NOTES.md)
+- [1.32](releases/1.32-NOTES.md)
+- [1.31](releases/1.31-NOTES.md)
+- [1.30](releases/1.30-NOTES.md)
+- [1.29](releases/1.29-NOTES.md)
+- [1.28](releases/1.28-NOTES.md)
+- [1.27](releases/1.27-NOTES.md)
+- [1.26](releases/1.26-NOTES.md)
+- [1.25](releases/1.25-NOTES.md)
+- [1.24](releases/1.24-NOTES.md)
+- [1.23](releases/1.23-NOTES.md)
+- [1.22](releases/1.22-NOTES.md)
+- [1.21](releases/1.21-NOTES.md)
+- [1.20](releases/1.20-NOTES.md)
+- [1.19](releases/1.19-NOTES.md)
+- [1.18](releases/1.18-NOTES.md)
+- [1.17](releases/1.17-NOTES.md)
+- [1.16](releases/1.16-NOTES.md)
+- [1.15](releases/1.15-NOTES.md)
+- [1.14](releases/1.14-NOTES.md)
+- [1.13](releases/1.13-NOTES.md)
+- [1.12](releases/1.12-NOTES.md)
+- [1.11](releases/1.11-NOTES.md)
+- [1.10](releases/1.10-NOTES.md)
+- [1.9](releases/1.9-NOTES.md)
+- [1.8](releases/1.8-NOTES.md)
+- [1.7](releases/1.7-NOTES.md)
+- [1.6](releases/1.6-NOTES.md)
+- [1.4](releases/1.4-NOTES.md)