[#17] Fixes to airshipctl docs
Various typo fixes in documents Various grammar and language changes for clarification Change-Id: I111bf45c90405a26d09a5254733a055c78b47407
This commit is contained in:
Ian H Pittwood
Ian Pittwood
parent
9a47c9b423
commit
6cb70e7eb3
@ -67,7 +67,7 @@ linters-settings:
|
||||
threshold: 150
|
||||
|
||||
errcheck:
|
||||
# report about not checking of errors in type assetions: `a := b.(MyStruct)`;
|
||||
# report about not checking of errors in type assertions: `a := b.(MyStruct)`;
|
||||
# default is false: such cases aren't reported by default.
|
||||
check-type-assertions: true
|
||||
|
||||
@ -176,7 +176,7 @@ linters-settings:
|
||||
unused:
|
||||
# treat code as a program (not a library) and report unused exported identifiers; default is false.
|
||||
# XXX: if you enable this setting, unused will report a lot of false-positives in text editors:
|
||||
# if it's called for subdir of a project it can't find funcs usages. All text editor integrations
|
||||
# if it's called for subdirectory of a project it can't find funcs usages. All text editor integrations
|
||||
# with golangci-lint call it on a directory with the changed file.
|
||||
check-exported: false
|
||||
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
# Contributing Guidelines
|
||||
|
||||
The airshipctl project accepts contributions via gerrit reviews. For help
|
||||
getting started with gerrit, see the official [OpenDev
|
||||
The airshipctl project accepts contributions via Gerrit reviews. For help
|
||||
getting started with Gerrit, see the official [OpenDev
|
||||
documentation](https://docs.openstack.org/contributors/common/setup-gerrit.html).
|
||||
This document outlines the process to help get your contribution accepted.
|
||||
|
||||
## Support Channels
|
||||
|
||||
Whether you are a user or contributor, official support channels are available
|
||||
[here](https://wiki.openstack.org/wiki/Airship#Get_in_Touch)
|
||||
[here](https://wiki.openstack.org/wiki/Airship#Get_in_Touch).
|
||||
|
||||
You can also report [bugs](https://airship.atlassian.net/issues/?jql=project%20%3D%20AIR%20AND%20issuetype%20%3D%20Bug%20order%20by%20created%20DESC).
|
||||
You can also report [bugs](
|
||||
https://airship.atlassian.net/issues/?jql=project%20%3D%20AIR%20AND%20issuetype%20%3D%20Bug%20order%20by%20created%20DESC).
|
||||
|
||||
|
||||
Before opening a new issue or submitting a patchset, it's helpful to search the
|
||||
bug reports above - it's likely that another user has already reported the issue you're
|
||||
facing, or it's a known issue that we're already aware of. It is also worth
|
||||
asking on the IRC channels.
|
||||
Before opening a new issue or submitting a change, it's helpful to search the
|
||||
bug reports above - it's likely that another user has already reported the
|
||||
issue you're facing, or it's a known issue that we're already aware of. It is
|
||||
also worth asking on the IRC channels.
|
||||
|
||||
## Story Lifecycle
|
||||
|
||||
@ -24,7 +24,7 @@ The airshipctl project uses Jira to track all efforts, whether those are
|
||||
contributions to this repository or other community projects. The Jira issues
|
||||
are a combination of epics, issues, subtasks, bugs, and milestones. We use
|
||||
epics to define large deliverables and many epics have been created already.
|
||||
The project assumes that developers trying to break down epics into managable
|
||||
The project assumes that developers trying to break down epics into manageable
|
||||
work will create their own issues/stories and any related subtasks to further
|
||||
breakdown their work. Milestones act as human readable goals for the sprint they
|
||||
are assigned to.
|
||||
@ -37,6 +37,9 @@ chronologically ordering work in Jira.
|
||||
|
||||
### Coding Conventions
|
||||
|
||||
Airship has a set of [coding conventions](https://airship-docs.readthedocs.io/en/latest/conventions.html) that are meant to cover all Airship subprojects.
|
||||
Airship has a set of [coding conventions](
|
||||
https://airship-docs.readthedocs.io/en/latest/conventions.html) that are meant
|
||||
to cover all Airship subprojects.
|
||||
|
||||
However, airshipctl also has its own specific coding conventions and standards in the official airshipctl [developer guide](docs/source/developers.md).
|
||||
However, airshipctl also has its own specific coding conventions and standards
|
||||
in the official airshipctl [developer guide](docs/source/developers.md).
|
||||
26
README.md
26
README.md
@ -2,11 +2,11 @@
|
||||
|
||||
## What is airshipctl
|
||||
|
||||
The `airshipctl` project is a CLI tool and go-lang library for declaratively
|
||||
managing infrastructure and software.
|
||||
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 opensource options such as the Cluster
|
||||
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.
|
||||
|
||||
@ -14,10 +14,10 @@ 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.
|
||||
- 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.
|
||||
- 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/).
|
||||
@ -42,28 +42,28 @@ 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
|
||||
2. 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
|
||||
3. Run `airshipctl document pull` to clone the document repositories in your
|
||||
Airship Configuration.
|
||||
1. When deploying against baremetal infrastructure, run `airshipctl bootstrap
|
||||
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.
|
||||
1. When deploying against baremetal infrastructure, run `airshipctl bootstrap
|
||||
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.
|
||||
1. Run `airshipctl cluster initinfra --clustertype=ephemeral` to bootstrap the
|
||||
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.
|
||||
1. Run `airshipctl clusterctl` to use the ephemeral Kubernetes host to provision
|
||||
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.
|
||||
1. Run `airshipctl cluster initinfra --clustertype=target` to bootstrap the new
|
||||
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.
|
||||
1. Run `airshipctl workflow submit sitemanage` to run the out of the box sitemanage
|
||||
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.
|
||||
|
||||
|
||||
@ -4,14 +4,14 @@
|
||||
|
||||
# Documentation
|
||||
sphinx>2.1.0
|
||||
oslosphinx>=4.7.0 # Apache-2.0
|
||||
oslosphinx>=4.7.0 # Apache-2.0
|
||||
sphinx_rtd_theme
|
||||
|
||||
# UML image generation
|
||||
plantuml
|
||||
|
||||
# Releasenotes
|
||||
reno>=2.5.0 # Apache-2.0
|
||||
reno>=2.5.0 # Apache-2.0
|
||||
|
||||
# Sphinx markdown extension
|
||||
recommonmark
|
||||
|
||||
@ -17,7 +17,7 @@ We use Make to build our programs. The simplest way to get started is:
|
||||
$ make build
|
||||
```
|
||||
|
||||
NOTE: The airshipctl application is a go module. This means you do not need to
|
||||
NOTE: The airshipctl application is a Go module. This means you do not need to
|
||||
clone the repository into `$GOPATH` in order to build it. You should be able to
|
||||
build it from any directory.
|
||||
|
||||
@ -75,17 +75,17 @@ We accept changes to the code via Gerrit pull requests. One workflow for doing
|
||||
this is as follows:
|
||||
|
||||
1. `git clone` the `opendev.org/airship/airshipctl` repository.
|
||||
2. Create a new working branch (`git checkout -b feat/my-feature`) and do your
|
||||
work on that branch.
|
||||
3. When you are ready for us to review, push your branch to gerrit using
|
||||
`git-review`. For more information on the gerrit workflow, see the [OpenDev
|
||||
2. Create a new working branch (`git checkout -b feature/my-feature`) and do your
|
||||
work on that branch. This will act as your topic in Gerrit.
|
||||
3. When you are ready for us to review, push your branch to Gerrit using
|
||||
`git-review`. For more information on the Gerrit workflow, see the [OpenDev
|
||||
documentation](
|
||||
https://docs.openstack.org/contributors/common/setup-gerrit.html).
|
||||
|
||||
### Go Conventions
|
||||
|
||||
We follow the Go coding style standards very closely. Typically, running `go
|
||||
fmt` will make your code beautiful for you.
|
||||
fmt -s -w ./` will make your code beautiful for you.
|
||||
|
||||
We also typically follow the conventions of `golangci-lint`.
|
||||
|
||||
|
||||
@ -1,10 +1,11 @@
|
||||
# Plugin Support
|
||||
|
||||
##### Table of Contents
|
||||
* [Compile-In Plugins](#compile-in)
|
||||
* [Fine Tuning a Build](#fine-tuning)
|
||||
## Table of Contents
|
||||
|
||||
* [Compile-In Plugins](#compile-in-plugins)
|
||||
* [Fine Tuning a Build](#fine-tuning-a-build)
|
||||
* [Command Selection](#command-selection)
|
||||
* [Accessing `airshipctl` settings](#settings)
|
||||
* [Accessing `airshipctl` settings](#accessing-airshipctl-settings)
|
||||
|
||||
Our requirements for `airshipctl` contain two very conflicting concepts. One,
|
||||
we'd like to assert that `airshipctl` is a statically linked executable, such
|
||||
@ -13,12 +14,10 @@ requirements can't coincide within the same project under the standard
|
||||
definition of a plugin. Our solution is to provide a more refined definition of
|
||||
what a plugin actually is.
|
||||
|
||||
<a name="compile-in" />
|
||||
|
||||
## Compile-In Plugins
|
||||
|
||||
In order to support plugins to an independent binary file, we use the concept
|
||||
of *compile-in plugins*. A *compile-in plugin* is an add-on that is built into
|
||||
of "compile-in plugins". A "compile-in plugin" is an add-on that is built into
|
||||
the main application at compile time, as opposed to runtime. This means that
|
||||
while `airshipctl` is a standalone application, it also acts as a sort of
|
||||
library. In fact, taking a deeper look at `airshipctl` reveals that the base
|
||||
@ -53,18 +52,28 @@ Usage:
|
||||
airshipctl [command]
|
||||
|
||||
Available Commands:
|
||||
bootstrap Bootstrap ephemeral Kubernetes cluster
|
||||
completion Generate autocompletions script for the specified shell (bash or zsh)
|
||||
config Modify airshipctl config files
|
||||
document manages deployment documents
|
||||
help Help about any command
|
||||
kubectl kubectl controls the Kubernetes cluster manager
|
||||
version Show the version number of airshipctl
|
||||
|
||||
Flags:
|
||||
--debug enable verbose output
|
||||
-h, --help help for airshipctl
|
||||
--airshipconf string Path to file for airshipctl configuration. (default "$HOME/.airship/config")
|
||||
--debug enable verbose output
|
||||
-h, --help help for airshipctl
|
||||
--kubeconfig string Path to kubeconfig associated with airshipctl configuration. (default "$HOME/.airship/kubeconfig")
|
||||
|
||||
Additional help topics:
|
||||
airshipctl cluster Control Kubernetes cluster
|
||||
|
||||
Use "airshipctl [command] --help" for more information about a command.
|
||||
```
|
||||
|
||||
Every other command is treated as a plugin. Changing `main` to the following
|
||||
adds the default commands, or "plugins", to the`airshipctl` tool:
|
||||
adds the default commands, or "plugins", to the `airshipctl` tool:
|
||||
|
||||
```go
|
||||
func main() {
|
||||
@ -81,8 +90,12 @@ Compiling and running now provides the following commands:
|
||||
|
||||
```
|
||||
Available Commands:
|
||||
bootstrap bootstraps airshipctl
|
||||
bootstrap Bootstrap ephemeral Kubernetes cluster
|
||||
completion Generate autocompletions script for the specified shell (bash or zsh)
|
||||
config Modify airshipctl config files
|
||||
document manages deployment documents
|
||||
help Help about any command
|
||||
kubectl kubectl controls the Kubernetes cluster manager
|
||||
version Show the version number of airshipctl
|
||||
------ more commands TBD ------
|
||||
```
|
||||
@ -124,8 +137,6 @@ func main() {
|
||||
}
|
||||
```
|
||||
|
||||
<a name="fine-tuning" />
|
||||
|
||||
## Fine Tuning a Build
|
||||
|
||||
There are a couple of ways in which a plugin author can fine tune their version
|
||||
@ -133,8 +144,6 @@ of `airshipctl`. These manifest as an ability to pick and choose various
|
||||
plugins (including the defaults), and capabilities for accessing the same
|
||||
settings as other `airshipctl` commands.
|
||||
|
||||
<a name="command-selection" />
|
||||
|
||||
### Command Selection
|
||||
|
||||
In the previous section, we introduced the `AddDefaultAirshipCTLCommands`
|
||||
@ -169,8 +178,6 @@ This can be particularly useful if a plugin author desires to "override" a
|
||||
specific functionality provided by a builtin command. For example, you might
|
||||
write your own `bootstrap` command and use it in place of the builtin.
|
||||
|
||||
<a name="settings" />
|
||||
|
||||
### Accessing `airshipctl` settings
|
||||
|
||||
The `airshipctl` will contain several settings which may be useful to a plugin
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Testing Guidelines
|
||||
|
||||
This document lays out several guidelines to secure high quality and
|
||||
This document lays out several guidelines to ensure quality and
|
||||
consistency throughout `airshipctl`'s test bed.
|
||||
|
||||
## Testing packages
|
||||
@ -8,6 +8,7 @@ consistency throughout `airshipctl`'s test bed.
|
||||
The `airshipctl` project uses the [testify] library, a thin wrapper around Go's
|
||||
builtin `testing` package. The `testify` package provides the following
|
||||
packages:
|
||||
|
||||
* `assert`: Functions from this package can be used to replace most calls to
|
||||
`t.Error`
|
||||
* `require`: Contains the same functions as above, but these functions should
|
||||
@ -19,7 +20,7 @@ packages:
|
||||
|
||||
Tests should cover at least __80%__ of the codebase. Anything less will cause
|
||||
the CI gates to fail. A developer should assert that their code meets this
|
||||
criteria before submitting a patchset. This check can be performed with one of
|
||||
criteria before submitting a change. This check can be performed with one of
|
||||
the following `make` targets:
|
||||
|
||||
```
|
||||
|
||||
@ -33,7 +33,7 @@ type CmdTest struct {
|
||||
// and arguments. The initial "airshipctl" is implied
|
||||
CmdLine string
|
||||
|
||||
// The instatiated version of the root airshipctl command to test
|
||||
// The instantiated version of the root airshipctl command to test
|
||||
Cmd *cobra.Command
|
||||
|
||||
// The expected error
|
||||
|
||||
Loading…
Reference in New Issue
Block a user