From 771536304a0cf4abd3ace82991f6a12ae8bad0f6 Mon Sep 17 00:00:00 2001 From: Drew Walters Date: Fri, 8 May 2020 19:35:02 +0000 Subject: [PATCH] Update stale README and reformat docs This change updates the stale README and makes it the landing page of our new documentation. This change also makes several formatting changes to make our documentation fit the new docs.airshipit.org framework. Lastly, some items from the original README have been updated for accuracy and moved to a separate page of the documentation. Change-Id: Iae898b36034640df4d35a430eb28fbda028f10dd Signed-off-by: Drew Walters --- README.md | 78 ------------------------------------- README.rst | 43 ++++++++++++++++++++ docs/source/architecture.md | 42 ++++++++++++++++++++ docs/source/conf.py | 4 ++ docs/source/index.rst | 20 ++++++---- 5 files changed, 101 insertions(+), 86 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/source/architecture.md diff --git a/README.md b/README.md deleted file mode 100644 index f331535bf..000000000 --- a/README.md +++ /dev/null @@ -1,78 +0,0 @@ -# airshipctl - -## What is airshipctl - -The `airshipctl` project is a CLI tool and Golang library for declarative -management of infrastructure and software. - -The goal for the project is to provide a seamless experience to operators -wishing to leverage the best of breed open source options such as the Cluster -API, Metal3-io, Kustomize, Kubeadm, and Argo -- into a straight forward and -easily approachable tool. - -This project is the heart of the effort to produce Airship 2.0, which has three -main evolutions from -[1.0](https://airshipit.readthedocs.io/projects/airship-docs/en/latest/): - -- Expand our use of entrenched upstream projects. -- Embrace Kubernetes Custom Resource Definitions (CRD) – Everything becomes an - Object in Kubernetes. -- Make the Airship control plane ephemeral. - -To learn more about the Airship 2.0 evolution, please check out the [Airship -Blog Series](https://www.airshipit.org/blog/). - -## Contributing - -This project is under heavy active development to reach an alpha state. - -New developers should read the [contributing guide](CONTRIBUTING.md) as -well as the [developer guide](docs/source/developers.md) in order to get started. - -## Architecture - -The `airshipctl` tool is designed to work against declarative infrastructure -housed in source control and manage the lifecycle of a site. - -![architecture diagram](docs/source/img/architecture.png) - -## Example Usage - -In a nutshell, users of `airshipctl` should be able to do the following: - -1. Create an `airshipctl` Airship Configuration for their site - sort of like a - kubeconfig file. -2. Create a set of declarative documents representing the infrastructure - (baremetal, cloud) and software. -3. Run `airshipctl document pull` to clone the document repositories in your - Airship Configuration. -4. When deploying against baremetal infrastructure, run `airshipctl bootstrap - isogen` to generate a self-contained ISO that can be used to boot the first - host in the cluster into an ephemeral Kubernetes node. -5. When deploying against baremetal infrastructure, run `airshipctl bootstrap - remotedirect` to remotely provision the first machine in the cluster using - the generated ISO, providing an ephemeral Kubernetes instance that - `airshipctl` can communicate with for subsequent steps. This ephemeral host - provides a foothold in the target environment so we can follow the standard - cluster-api bootstrap flow. -6. Run `airshipctl cluster initinfra --clustertype=ephemeral` to bootstrap the - new ephemeral cluster with enough of the chosen cluster-api provider - components to provision the target cluster. -7. Run `airshipctl clusterctl` to use the ephemeral Kubernetes host to provision - at least one node of the target cluster using the cluster-api bootstrap flow. -8. Run `airshipctl cluster initinfra --clustertype=target` to bootstrap the new - target cluster with any remaining infrastructure necessary to begin running - more complex workflows such as Argo. -9. Run `airshipctl workflow submit sitemanage` to run the out of the box sitemanage - workflow, which will leverage Argo to handle bootstrapping the remaining - infrastructure as well as deploying and/or updating software. - -As users evolve their sites declaration, whether adding additional -infrastructure, or software declarations, they can re-run `airshipctl workflow -submit sitemanage` to introduce those changes to the site. - -## Project Resources - -- Airship Website - [airshipit.org](https://airshipit.org) -- Airship UI Project - [opendev.org/airship/airshipui](https://opendev.org/airship/airshipui) -- airshipctl Issue Tracker - [https://github.com/airshipit/airshipctl/issues](https://github.com/airshipit/airshipctl/issues) diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..caa281852 --- /dev/null +++ b/README.rst @@ -0,0 +1,43 @@ +Airshipctl +========== + +Airshipctl is a command-line interface that enables users to manage declarative +infrastructure and software. + +Airshipctl aims to provide a seamless experience for operators wishing to +leverage the best open source options such as the `Cluster API`_, `Metal +Kubed`_, Kustomize_, and kubeadm_ by providing a straight forward and easily +approachable interface. + +This project is the heart of our effort to produce Airship 2.0, which has +three main evolutions from `Airship 1.0`_: + +* Expand our use of entrenched upstream projects. +* Embrace Kubernetes Custom Resource Definitions (CRD) – everything becomes an + object in Kubernetes. +* Make the Airship control plane ephemeral. + +To learn more about the Airship 2.0 evolution, reference the +`Airship blog series`_. + +Contributing +------------ + +Airshipctl is under active development and welcomes new developers! Please +read our `developer guide`_ to begin contributing. + +We also encourage new contributors and operators alike to join us in our +`Slack workspace`_ and subscribe to our `mailing lists`_. + +You can learn more about Airship on the `Airship wiki`_. + +.. _Airship 1.0: https://docs.airshipit.org/treasuremap +.. _Airship blog series: https://www.airshipit.org/blog/airship-blog-series-1-evolution-towards-2.0 +.. _Airship wiki: https://wiki.openstack.org/wiki/Airship +.. _Cluster API: https://github.com/kubernetes-sigs/cluster-api +.. _developer guide: https://docs.airshipit.org/airshipctl/developers.html +.. _kubeadm: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm +.. _Kustomize: https://github.com/kubernetes-sigs/kustomize +.. _mailing lists: http://lists.airshipit.org/cgi-bin/mailman/listinfo +.. _Metal Kubed: https://metal3.io +.. _Slack workspace: http://airshipit.org/slack diff --git a/docs/source/architecture.md b/docs/source/architecture.md new file mode 100644 index 000000000..2b44652bd --- /dev/null +++ b/docs/source/architecture.md @@ -0,0 +1,42 @@ +## Architecture + +The `airshipctl` tool is designed to work against declarative infrastructure +housed in source control and manage the lifecycle of a site. + +![architecture diagram](img/architecture.png) + +## Example Usage + +In a nutshell, users of `airshipctl` should be able to do the following: + +1. Create an `airshipctl` Airship Configuration for their site - sort of like a + kubeconfig file. Airshipctl can create a pre-configured config file by + running `airshipctl config init`. +2. Create a set of declarative documents representing the infrastructure + (baremetal, cloud) and software. +3. Run `airshipctl document pull` to clone the document repositories in your + Airship Configuration. +4. When deploying against baremetal infrastructure, run + `airshipctl baremetal isogen` to generate a self-contained ISO that can be + used to boot the first host in the cluster into an ephemeral Kubernetes node. +5. When deploying against baremetal infrastructure, run + `airshipctl baremetal remotedirect` to remotely provision the first machine + in the cluster using the generated ISO, providing an ephemeral Kubernetes + instance that `airshipctl` can communicate with for subsequent steps. This + ephemeral host provides a foothold in the target environment so we can follow + the standard cluster-api bootstrap flow. +6. Run `airshipctl phase apply initinfra` to bootstrap the new ephemeral cluster + with enough of the chosen cluster-api provider components to provision the + target cluster. +7. Run `airshipctl clusterctl` to use the ephemeral Kubernetes host to provision + at least one node of the target cluster using the cluster-api bootstrap flow. +8. Run `airshipctl cluster initinfra --clustertype=target` to bootstrap the new + target cluster with any remaining infrastructure necessary to begin running + more complex workflows such as Argo. +9. Run `airshipctl workflow submit sitemanage` to run the out of the box sitemanage + workflow, which will leverage Argo to handle bootstrapping the remaining + infrastructure as well as deploying and/or updating software. + +As users evolve their sites declaration, whether adding additional +infrastructure, or software declarations, they can re-run `airshipctl workflow +submit sitemanage` to introduce those changes to the site. diff --git a/docs/source/conf.py b/docs/source/conf.py index 3fb617a16..f6da51a60 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,6 +48,10 @@ exclude_patterns = [] # html_logo = "img/airship.logo.white.svg" html_theme = "sphinx_rtd_theme" +html_theme_options = { + 'display_version': False, + 'logo_only': True +} html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Add any paths that contain custom static files (such as style sheets) here, diff --git a/docs/source/index.rst b/docs/source/index.rst index 4215e2382..f874a49ac 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,14 +14,18 @@ License for the specific language governing permissions and limitations under the License. -======================== -airshipctl Documentation -======================== +====================================== +Welcome to airshipctl's Documentation! +====================================== + +.. include:: ../../README.rst .. toctree:: - :maxdepth: 2 + :hidden: + :maxdepth: 2 - developers - plugins - testing-guidelines - cli/cli \ No newline at end of file + architecture + developers + plugins + testing-guidelines + cli/cli