diff --git a/README.md b/README.md index f1f33f148..d898f3ab2 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,77 @@ # airshipctl -### Custom Plugins Tutorial +## What is airshipctl -This tutorial walks through a very basic plugin for `airshipctl`. For a more -involved example, see [Plugin Support](docs/plugins.md) +The `airshipctl` project is a CLI tool and go-lang library for declaratively +managing infrastructure and software. -The following steps will get you started with a very rudimentary example plugin -for airshipctl. First, create a directory for your project outside of the -GOPATH: -``` -mkdir /tmp/example -cd /tmp/example -``` -This project will need to be a go module. You can initialize a module named -`example` with the following: -``` -go mod init example -``` -Note that modules are a relatively new feature added to Go, so you'll need to -be running Go1.11 or greater. Also note that most modules will follow a naming -schema that matches the remote version control system. A more realistice module -name might look something like `opendev.org/airship/exampleplugin`. +The goal for the project is to provide a seamless experience to operators +wishing to leverage the best of breed opensource options such as the Cluster +API, Metal3-io, Kustomize, Kubeadm, and Argo -- into a straight forward and +easily approachable tool. -Next, create a file `main.go` and populate it with the following: -```go -package main +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/): -import ( - "fmt" - "os" +- 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. - "opendev.org/airship/airshipctl/cmd" - "github.com/spf13/cobra" -) +To learn more about the Airship 2.0 evolution, please check out the [Airship +Blog Series](https://www.airshipit.org/blog/). -func main() { - rootCmd, _, err := cmd.NewRootCmd(os.Stdout) - if err != nil { - fmt.Fprintf(os.Stderr, "Failed to create root airshipctl command: %s\n", err.Error()) - os.Exit(1) - } +## Contributing - exampleCmd := &cobra.Command{ - Use: "example", - Short: "an example plugin", - Run: func(cmd *cobra.Command, args []string) { - fmt.Fprintln(os.Stdout, "Hello airshipctl!") - }, - } +This project is under heavy active development to reach an alpha state. - rootCmd.AddCommand(exampleCmd) - if err := rootCmd.Execute(); err != nil { - fmt.Fprintf(os.Stderr, "Failure during execution: %s\n", err.Error()) - os.Exit(1) - } -} -``` -And finally, run the build command to download and compile `airshipctl`: -``` -go build -o airshipctl -``` -Now that you've built `airshipctl`, you can access your plugin with the following command: -``` -./airshipctl example -``` +New developers should read the [contributing guide](/CONTRIBUTING.md) as +well as the [developer guide](/docs/developer.md) in order to get started. -You may have noticed that this example ignores the second return value from -cmd.NewRootCmd. This value is a pointer to the AirshipCTLSettings, which -contains various configuration details, such as the debug flag and the path to -the config file\*. A useful paradigm involves embedding this object into a -custom ExampleSettings struct. This can be seen in the demo repo. +## Architecture -For a more involved example, see [Plugin Support](docs/plugins.md) +The `airshipctl` tool is designed to work against declarative infrastructure +housed in source control and manage the lifecycle of a site. -\* Work in progress +![architecture diagram](/docs/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. +1. Create a set of declarative documents representing the infrastructure + (baremetal, cloud) and software. +1. Run `airshipctl document pull` to clone the document repositories in your + Airship Configuration. +1. 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. +1. 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. +1. 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. +1. 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. +1. 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. +1. 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](http://airshipit.org) +- Airship UI Project - [github.com/airshipit/airshipui](https://github.com/airshipit/airshipui) \ No newline at end of file diff --git a/docs/img/architecture.png b/docs/img/architecture.png new file mode 100644 index 000000000..1fdce6dd8 Binary files /dev/null and b/docs/img/architecture.png differ