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