Merge "Update stale README and reformat docs"
This commit is contained in:
Zuul
Gerrit Code Review
commit
88dddbf5f2
78
README.md
78
README.md
@ -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.
|
||||
|
||||
|
||||
|
||||
## 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)
|
||||
43
README.rst
Normal file
43
README.rst
Normal file
@ -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
|
||||
42
docs/source/architecture.md
Normal file
42
docs/source/architecture.md
Normal file
@ -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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
@ -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,
|
||||
|
||||
@ -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
|
||||
architecture
|
||||
developers
|
||||
plugins
|
||||
testing-guidelines
|
||||
cli/cli
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user