airship/airshipctl
Code Issues Proposed changes

[#17] Fixes to airshipctl docs

Browse Source 
Various typo fixes in documents

Various grammar and language changes for clarification

Change-Id: I111bf45c90405a26d09a5254733a055c78b47407
This commit is contained in:
Ian H Pittwood 2020-02-06 15:20:47 -06:00 committed by Ian Pittwood
parent 9a47c9b423
commit 6cb70e7eb3
8 changed files with 66 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.golangci.yaml
View File

@ -67,7 +67,7 @@ linters-settings:
threshold: 150 threshold: 150
errcheck: 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. # default is false: such cases aren't reported by default.
check-type-assertions: true check-type-assertions: true
@ -176,7 +176,7 @@ linters-settings:
unused: unused:
# treat code as a program (not a library) and report unused exported identifiers; default is false. # 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: # 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. # with golangci-lint call it on a directory with the changed file.
check-exported: false check-exported: false

27
CONTRIBUTING.md
View File

@ -1,22 +1,22 @@
# Contributing Guidelines # Contributing Guidelines
The airshipctl project accepts contributions via gerrit reviews. For help The airshipctl project accepts contributions via Gerrit reviews. For help
getting started with gerrit, see the official [OpenDev getting started with Gerrit, see the official [OpenDev
documentation](https://docs.openstack.org/contributors/common/setup-gerrit.html). documentation](https://docs.openstack.org/contributors/common/setup-gerrit.html).
This document outlines the process to help get your contribution accepted. This document outlines the process to help get your contribution accepted.
## Support Channels ## Support Channels
Whether you are a user or contributor, official support channels are available 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 change, it's helpful to search the
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
bug reports above - it's likely that another user has already reported the issue you're issue you're facing, or it's a known issue that we're already aware of. It is
facing, or it's a known issue that we're already aware of. It is also worth also worth asking on the IRC channels.
asking on the IRC channels.
## Story Lifecycle ## 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 contributions to this repository or other community projects. The Jira issues
are a combination of epics, issues, subtasks, bugs, and milestones. We use are a combination of epics, issues, subtasks, bugs, and milestones. We use
epics to define large deliverables and many epics have been created already. 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 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 breakdown their work. Milestones act as human readable goals for the sprint they
are assigned to. are assigned to.
@ -37,6 +37,9 @@ chronologically ordering work in Jira.
### Coding Conventions ### 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
View File

@ -2,11 +2,11 @@
## What is airshipctl ## What is airshipctl
The `airshipctl` project is a CLI tool and go-lang library for declaratively The `airshipctl` project is a CLI tool and Golang library for declarative
managing infrastructure and software. management of infrastructure and software.
The goal for the project is to provide a seamless experience to operators 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 API, Metal3-io, Kustomize, Kubeadm, and Argo -- into a straight forward and
easily approachable tool. 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 main evolutions from
[1.0](https://airshipit.readthedocs.io/projects/airship-docs/en/latest/): [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 - Embrace Kubernetes Custom Resource Definitions (CRD) – Everything becomes an
Object in Kubernetes. 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 To learn more about the Airship 2.0 evolution, please check out the [Airship
Blog Series](https://www.airshipit.org/blog/). 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 1. Create an `airshipctl` Airship Configuration for their site - sort of like a
kubeconfig file. 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. (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. 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 isogen` to generate a self-contained ISO that can be used to boot the first
host in the cluster into an ephemeral Kubernetes node. 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 remotedirect` to remotely provision the first machine in the cluster using
the generated ISO, providing an ephemeral Kubernetes instance that the generated ISO, providing an ephemeral Kubernetes instance that
`airshipctl` can communicate with for subsequent steps. This ephemeral host `airshipctl` can communicate with for subsequent steps. This ephemeral host
provides a foothold in the target environment so we can follow the standard provides a foothold in the target environment so we can follow the standard
cluster-api bootstrap flow. 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 new ephemeral cluster with enough of the chosen cluster-api provider
components to provision the target cluster. 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. 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 target cluster with any remaining infrastructure necessary to begin running
more complex workflows such as Argo. 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 workflow, which will leverage Argo to handle bootstrapping the remaining
infrastructure as well as deploying and/or updating software. infrastructure as well as deploying and/or updating software.

4
docs/requirements.txt
View File

@ -4,14 +4,14 @@
# Documentation # Documentation
sphinx>2.1.0 sphinx>2.1.0
oslosphinx>=4.7.0 # Apache-2.0 oslosphinx>=4.7.0 # Apache-2.0
sphinx_rtd_theme sphinx_rtd_theme
# UML image generation # UML image generation
plantuml plantuml
# Releasenotes # Releasenotes
reno>=2.5.0 # Apache-2.0 reno>=2.5.0 # Apache-2.0
# Sphinx markdown extension # Sphinx markdown extension
recommonmark recommonmark

12
docs/source/developers.md
View File

@ -17,7 +17,7 @@ We use Make to build our programs. The simplest way to get started is:
$ make build $ 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 clone the repository into `$GOPATH` in order to build it. You should be able to
build it from any directory. 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: this is as follows:
1. `git clone` the `opendev.org/airship/airshipctl` repository. 1. `git clone` the `opendev.org/airship/airshipctl` repository.
2. Create a new working branch (`git checkout -b feat/my-feature`) and do your 2. Create a new working branch (`git checkout -b feature/my-feature`) and do your
work on that branch. 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 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 `git-review`. For more information on the Gerrit workflow, see the [OpenDev
documentation]( documentation](
https://docs.openstack.org/contributors/common/setup-gerrit.html). https://docs.openstack.org/contributors/common/setup-gerrit.html).
### Go Conventions ### Go Conventions
We follow the Go coding style standards very closely. Typically, running `go 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`. We also typically follow the conventions of `golangci-lint`.

41
docs/source/plugins.md
View File

@ -1,10 +1,11 @@
# Plugin Support # Plugin Support
##### Table of Contents ## Table of Contents
* [Compile-In Plugins](#compile-in)
* [Fine Tuning a Build](#fine-tuning) * [Compile-In Plugins](#compile-in-plugins)
* [Fine Tuning a Build](#fine-tuning-a-build)
* [Command Selection](#command-selection) * [Command Selection](#command-selection)
* [Accessing `airshipctl` settings](#settings) * [Accessing `airshipctl` settings](#accessing-airshipctl-settings)
Our requirements for `airshipctl` contain two very conflicting concepts. One, Our requirements for `airshipctl` contain two very conflicting concepts. One,
we'd like to assert that `airshipctl` is a statically linked executable, such 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 definition of a plugin. Our solution is to provide a more refined definition of
what a plugin actually is. what a plugin actually is.
<a name="compile-in" />
## Compile-In Plugins ## Compile-In Plugins
In order to support plugins to an independent binary file, we use the concept 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 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 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 library. In fact, taking a deeper look at `airshipctl` reveals that the base
@ -53,18 +52,28 @@ Usage:
airshipctl [command] airshipctl [command]
Available Commands: 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 help Help about any command
kubectl kubectl controls the Kubernetes cluster manager
version Show the version number of airshipctl version Show the version number of airshipctl
Flags: Flags:
--debug enable verbose output --airshipconf string Path to file for airshipctl configuration. (default "$HOME/.airship/config")
-h, --help help for airshipctl --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. Use "airshipctl [command] --help" for more information about a command.
``` ```
Every other command is treated as a plugin. Changing `main` to the following 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 ```go
func main() { func main() {
@ -81,8 +90,12 @@ Compiling and running now provides the following commands:
``` ```
Available 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 help Help about any command
kubectl kubectl controls the Kubernetes cluster manager
version Show the version number of airshipctl version Show the version number of airshipctl
------ more commands TBD ------ ------ more commands TBD ------
``` ```
@ -124,8 +137,6 @@ func main() {
} }
``` ```
<a name="fine-tuning" />
## Fine Tuning a Build ## Fine Tuning a Build
There are a couple of ways in which a plugin author can fine tune their version 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 plugins (including the defaults), and capabilities for accessing the same
settings as other `airshipctl` commands. settings as other `airshipctl` commands.
<a name="command-selection" />
### Command Selection ### Command Selection
In the previous section, we introduced the `AddDefaultAirshipCTLCommands` 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 specific functionality provided by a builtin command. For example, you might
write your own `bootstrap` command and use it in place of the builtin. write your own `bootstrap` command and use it in place of the builtin.
<a name="settings" />
### Accessing `airshipctl` settings ### Accessing `airshipctl` settings
The `airshipctl` will contain several settings which may be useful to a plugin The `airshipctl` will contain several settings which may be useful to a plugin

5
docs/source/testing-guidelines.md
View File

@ -1,6 +1,6 @@
# Testing Guidelines # 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. consistency throughout `airshipctl`'s test bed.
## Testing packages ## 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 The `airshipctl` project uses the [testify] library, a thin wrapper around Go's
builtin `testing` package. The `testify` package provides the following builtin `testing` package. The `testify` package provides the following
packages: packages:
* `assert`: Functions from this package can be used to replace most calls to * `assert`: Functions from this package can be used to replace most calls to
`t.Error` `t.Error`
* `require`: Contains the same functions as above, but these functions should * `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 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 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: the following `make` targets:
``` ```

2
testutil/utilities.go
View File

@ -33,7 +33,7 @@ type CmdTest struct {
// and arguments. The initial "airshipctl" is implied // and arguments. The initial "airshipctl" is implied
CmdLine string 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 Cmd *cobra.Command
// The expected error // The expected error