airship/docs
Code Issues Proposed changes

Airship 2 docs working tree

Browse Source 
Created Airship 2 docs working tree. Added minor copyright changes
(years update and AT&T -> Airship authors).

Change-Id: I7a22c256142d858c9f0fdb8a9c473871e0943e3a
This commit is contained in:
Roman Gorshunov 2021-03-22 09:37:53 +01:00
parent 3efecc3d91
commit 285b67a7e5
42 changed files with 675 additions and 1538 deletions

3
.zuul.yaml

@ -1,3 +1,6 @@
# Copyright 2019-2021 The Airship authors.
# All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

3
Makefile

@ -1,4 +1,5 @@
# Copyright 2019 AT&T Intellectual Property. All other rights reserved.
# Copyright 2019-2021 The Airship authors.
# All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.

56
doc/examples/Dockerfile.opensuse_15

@ -1,56 +0,0 @@
# Simplified example Dockerfile.opensuse_15
ARG FROM=opensuse/leap:15.1
FROM ${FROM} as builder
ENV LC_ALL=C.UTF-8, LANG=C.UTF-8
# Don't run 'zypper up', 'apt-get upgrade' and similar. List packages
# being installed in alphabetical order to avoid possible merge
# conflicts and make it easy to read. Indent commands with spaces.
RUN set -ex && \
mkdir -p /armada && \
zypper refresh && \
zypper --non-interactive install \
ca-certificates \
curl \
gcc \
git \
libopenssl-devel \
make \
netcfg \
python3 \
python3-devel \
python3-pip \
python3-setuptools \
tar
# ...
ARG FROM=opensuse/leap:15.1
FROM ${FROM}
LABEL org.opencontainers.image.authors='airship-discuss@lists.airshipit.org, irc://#airshipit@freenode' \
org.opencontainers.image.url='https://airshipit.org' \
org.opencontainers.image.documentation='https://airship-armada.readthedocs.org' \
org.opencontainers.image.source='https://opendev.org/airship/armada' \
org.opencontainers.image.vendor='The Airship Authors' \
org.opencontainers.image.licenses='Apache-2.0'
ENV LC_ALL=C.UTF-8, LANG=C.UTF-8, UID=1000, GID=1000
ENTRYPOINT ["./entrypoint.sh"]
CMD ["server"]
COPY --from=builder /armada .
RUN useradd -u ${UID} -g ${GID} -d /armada airship
RUN set -ex && \
zypper refresh && \
zypper --non-interactive install \
ca-certificates \
python3
# ...
USER airship

20
doc/source/airship2/airship-in-a-pod.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Airship in a Pod (AIAP)
=======================
Airship in a Pod (AIAP)

20
doc/source/airship2/airshipctl.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
airshipctl
==========
airshipctl

28
doc/source/airship2/architecture.rst Normal file

@ -0,0 +1,28 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Airship 2 Architecture
======================
Airship 2 Architecture
.. toctree::
:caption: Airship 2 Architecture
:maxdepth: 1
airshipctl.rst
sip.rst
vino.rst

21
doc/source/airship2/basics.rst Normal file

@ -0,0 +1,21 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Airship 2 Basics
================
Basics.

20
doc/source/airship2/cheatsheet.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Airship 2 Cheat Sheets
======================
Airship 2 Cheat Sheets

26
doc/source/airship2/contributing.rst Normal file

@ -0,0 +1,26 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
How to Contrubute to Airship
============================
How to Contrubute to Airship
.. toctree::
:caption: How to Contrubute to Airship
:maxdepth: 1
developers.rst

27
doc/source/airship2/cookbook.rst Normal file

@ -0,0 +1,27 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Airship 2 Cookbook
==================
Airship 2 Cookbook
.. toctree::
:caption: Airship 2 Cookbook
:maxdepth: 1
site-authoring-guide.rst
site-deployment-guide.rst

101
doc/source/airship2/developers.rst Normal file

@ -0,0 +1,101 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
================
Developers Guide
================
Thank you for your interest in Airship. Our community is eager to help you
contribute to the success of our project and welcome you as a member of our
community!
We invite you to reach out to us at any time via the `Airship mailing list`_ or
on our `Slack workspace`_.
Welcome aboard!
.. _Airship mailing list: http://lists.airshipit.org
.. _Slack workspace: http://airshipit.org/slack
=====================
Airship 2 Development
=====================
Development is underway on Airship 2: the educated evolution of Airship 1,
designed with our experience using Airship in production. Airship 2 makes the
Airship control plane ephemeral, leverages entrenched upstream projects such as
the `Cluster API`_, `Metal Kubed`_, Kustomize_, and `kubeadm`_, and embraces
Kubernetes Custom Resource Definitions (CRDs). To learn more about the Airship
2.0 evolution, see the `Airship 2 evolution blog series`_.
Each Airship 2 project has its own development guidelines. Join the ongoing Airship 2
development by referencing the `airshipctl`_ or the `airshipui`_ documentation.
.. _airshipctl: https://docs.airshipit.org/airshipctl/developers.html
.. _Airship 2 evolution blog series: https://www.airshipit.org/blog/airship-blog-series-1-evolution-towards-2.0
.. _airshipui: https://docs.airshipit.org/airshipui/developers.html
.. _Cluster API: https://github.com/kubernetes-sigs/cluster-api
.. _kubeadm: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm
.. _Kustomize: https://github.com/kubernetes-sigs/kustomize
.. _Metal Kubed: https://metal3.io
Pushing code
------------
Airship uses the `OpenDev gerrit`_ for code review. Refer to the `OpenStack
Contributing Guide`_ for a tutorial on submitting changes to Gerrit code
review.
.. _OpenDev gerrit: https://review.opendev.org
.. _OpenStack Contributing Guide: https://docs.openstack.org/horizon/latest/contributor/contributing.html
Next steps
----------
Upon pushing a change to gerrit, Zuul continuous integration will post job
results on your patch. Refer to the job output by clicking on the job itself to
determine if further action is required. If it's not clear why a job failed,
please reach out to a team member in IRC. We are happy to assist!
Assuming all continuous integration jobs succeed, Airship community members and
core developers will review your patch and provide feedback. Many patches are
submitted to Airship projects each day. If your patch does not receive feedback
for several days, please reach out using IRC or the Airship mailing list.
Merging code
------------
Like most OpenDev projects, Airship patches require two +2 code review votes
from core members to merge. Once you have addressed all outstanding feedback,
your change will be merged.
Beyond
------
Congratulations! After your first change merges, please keep up-to-date with
the team. We hold two weekly meetings for project and design discussion:
Our weekly #airshipit IRC meeting provides an opportunity to discuss project
operations.
Our weekly design call provides an opportunity for in-depth discussion of new
and existing Airship features.
For more information on the times of each meeting, refer to the `Airship
wiki`_.
.. _Airship wiki: https://wiki.openstack.org/wiki/Airship

20
doc/source/airship2/faq.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
FAQs
====
FAQs

20
doc/source/airship2/howto-videos.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
How To Videos
=============
How To Videos

28
doc/source/airship2/howto.rst Normal file

@ -0,0 +1,28 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
How to Use Airship 2
====================
How to Use Airship 2
.. toctree::
:caption: How to Use Airship 2
:maxdepth: 1
operations-guide.rst
user-guide.rst
troubleshooting-guide.rst

20
doc/source/airship2/operations-guide.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Operations Guide
================
Operations Guide

28
doc/source/airship2/other.rst Normal file

@ -0,0 +1,28 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Other topics
============
Treasuremap
-----------
Treasuremap
Jarvis (airship/charts)
-----------------------
Jarvis (airship/charts)

26
doc/source/airship2/production.rst Normal file

@ -0,0 +1,26 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Deploying Production Ready Airship 2 Cluster
============================================
Deploying Production Ready Airship Cluster
.. toctree::
:caption: Deploying Production Ready Airship Cluster
:maxdepth: 1
cookbook.rst

20
doc/source/airship2/quick-start-guide.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Quick start Guide
=================
Quick start Guide

30
doc/source/airship2/reference.rst Normal file

@ -0,0 +1,30 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Airship 2 Reference
===================
Airship 2 Reference
.. toctree::
:caption: Airship 2 Reference
:maxdepth: 1
faq.rst
../learn/glossary.rst
howto-videos.rst
cheatsheet.rst
troubleshooting-guide.rst

30
doc/source/airship2/release-notes.rst Normal file

@ -0,0 +1,30 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Release Notes
=============
Release Notes
Version N Release Notes
-----------------------
Version N Release Notes
Version N-1 Release Notes
-------------------------
Version N-1 Release Notes

20
doc/source/airship2/sip.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
SIP
===
SIP

20
doc/source/airship2/site-authoring-guide.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Site Authoring Guide
====================
Site Authoring Guide

20
doc/source/airship2/site-deployment-guide.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Site Deployment Guide
=====================
Site Deployment Guide

20
doc/source/airship2/training.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Airship 2 Training
==================
Airship 2 Training

20
doc/source/airship2/troubleshooting-guide.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Troubleshooting Guide
=====================
Troubleshooting Guide

27
doc/source/airship2/try.rst Normal file

@ -0,0 +1,27 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Try Airship 2
=============
Try Airship 2
.. toctree::
:caption: Try Airship 2
:maxdepth: 1
airship-in-a-pod.rst
quick-start-guide.rst

20
doc/source/airship2/user-guide.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
General User Guide
==================
General User Guide

20
doc/source/airship2/vino.rst Normal file

@ -0,0 +1,20 @@
..
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
ViNO
====
ViNO

2
doc/source/conf.py

@ -49,7 +49,7 @@ master_doc = 'index'
# General information about the project.
project = 'Airship Project'
copyright = '2019-2020, The Airship Authors'
copyright = '2019-2021, The Airship Authors'
author = 'The Airship Authors'
# The language for content autogenerated by Sphinx. Refer to documentation

351
doc/source/develop/api-conventions.rst

@ -1,351 +0,0 @@
..
Copyright 2017 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _api-conventions:
API Conventions
===============
A collection of conventions that components of Airship
utilize for their REST APIs
Resource path naming
--------------------
- Resource paths nodes follow an all lower case naming scheme, and
pluralize the resource names. Nodes that refer to keys, ids or names that
are externally controlled, the external naming will be honored.
- The version of the API resource path will be prefixed before the first
node of the path for that resource using v#.# format.
- By default and unless otherwise noted, the API will be namespaced by /api
before the version. For the purposes of documentation, this will not be
specified in each of the resource paths below. In more complex APIs, Airship
components may use values other than /api to be more specific to point to a
particular service.
::
/api/v1.0/sampleresources/ExTeRnAlNAME-1234
^ ^ ^ ^
| | | defer to external naming
| | plural
| lower case
version here
Status responses
----------------
Status responses, and more specifically error responses (HTTP response body
accompanying 4xx and 5xx series responses where possible) are a customized
version of the `Kubernetes standard for error representation`_. Airship
utilizes the details field in a more formalized way to represent multiple
messages related to a status response, as follows:
::
{
"kind": "Status",
"apiVersion": "v{{#.#}}",
"metadata": {},
"status": "{{Success | Failure}}",
"message": "{{message phrase}}",
"reason": "{{reason name}}",
"details": {
"errorCount": {{n}},
"messageList": [
{ "message" : "{{message contents}}",
"error": true|false,
"kind": "SimpleMessage" }
...
]
},
"code": {{http status code}}
}
such that:
* The metadata field is optionally present, as an empty object. Clients should
be ready to receive this field, but services are not required to produce it.
* The message phrase is a terse but descriptive message indicating what has
happened.
* The reason name is the short name indicating the cause of the status. It
should be a camel cased phrase-as-a-word, to mimic the Kubernetes status
usage.
* The details field is optional.
* If used, the details follow the shown format, with an errorCount and
messageList field present.
- The repeating entity inside the messageList can be decorated with as
many other fields as are useful, but at least have a message field and
error field.
- A kind field is optional, but if used will indicate the presence of
other fields. By default, the kind field is assumed to be
"SimpleMessage", which requires only the aforementioned message and
error fields.
- The errorCount field is an integer representing the count of messageList
entities that have ``error: true``
* When using this document as the body of a HTTP response, ``code`` is
populated with a valid `HTTP status code`_
Required Headers
----------------
X-Auth-Token
The auth token to identify the invoking user. Required unless the resource is
explictly unauthenticated.
Optional Headers
----------------
X-Context-Marker
A context id that will be carried on all logs for this client-provided
marker. This marker may only be a 36-character canonical representation of an
UUID (8-4-4-4-12)
X-End-User
The user name of the initial invoker that will be carried on all logs for
user tracing cross components. Shipyard doesn't support this header and when
passed, it will be ignored.
Validation API
--------------
All Airship components that participate in validation of the design supplied to
a site implement a common resource to perform document validations. Document
validations are synchronous.
Because of the different sources of documents that should be supported, a
flexible input descriptor is used to indicate from where an Airship component
will retrieve the documents to be validated.
POST /v1.0/validatedesign
~~~~~~~~~~~~~~~~~~~~~~~~~
Invokes an Airship component to perform validations against the documents
specified by the input structure. Synchronous.
Input structure
^^^^^^^^^^^^^^^
::
{
rel : "design",
href: "deckhand+https://{{deckhand_url}}/revisions/{{revision_id}}/rendered-documents",
type: "application/x-yaml"
}
Output structure
^^^^^^^^^^^^^^^^
The output structure reuses the Kubernetes Status kind to represent the result
of validations. The Status kind will be returned for both successful and failed
validation to maintain a consistent of interface. If there are additional
diagnostics that associate to a particular validation, the entries in the
messageList should be of kind "ValidationMessage" (preferred), or
"SimpleMessage" (assumed default base message kind).
Failure message example using a ValidationMessage kind for the messageList::
{
"kind": "Status",
"apiVersion": "v1.0",
"metadata": {},
"status": "Failure",
"message": "{{Component Name}} validations failed",
"reason": "Validation",
"details": {
"errorCount": {{n}},
"messageList": [
{ "message" : "{{validation failure message}}",
"error": true,
"name": "{{identifying name of the validation}}",
"documents": [
{ "schema": "{{schema and name of the document being validated}}",
"name": "{{name of the document being validated}}"
},
...
]
"level": "Error",
"diagnostic": "{{information about what lead to the message}}",
"kind": "ValidationMessage" },
...
]
},
"code": 400
}
Success message example::
{
"kind": "Status",
"apiVersion": "v1.0",
"metadata": {},
"status": "Success",
"message": "{{Component Name}} validations succeeded",
"reason": "Validation",
"details": {
"errorCount": 0,
"messageList": []
},
"code": 200
}
ValidationMessage Message Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ValidationMessage message type is used to provide more information about
validation results than a SimpleMessage provides. These are the fields of a
ValidationMessage:
- documents (optional): If applicable to configuration documents, specifies
the design documents by schema and name that were involved in the specific
validation. If the documents element is not provided, or is an empty list,
the assumption is that the validation is not traced to a document, and may
be a validaiton of environmental or process needs.
- schema (required): The schema of the document.
E.g. drydock/NetworkLink/v1
- name (required): The name of the document.
E.g. pxe-rack1
- error (required): true if the message indcates an error, false if the
message indicates a non-error.
- kind (required): ValidationMessage
- level (required): The severity of the validation result. This should align
with the error field value. Valid values are "Error", "Warning", and
"Info".
- message (required): The more complete message indicating the result of the
validation.
E.g.: MTU 8972 for pxe-rack1 is invalid for standard (non-jumbo) frames
- name (required): The name of the validation being performed. This is a short
name that identifies the validation among a full set of validations. It is
preferred to use non-action words to identify the validation.
E.g. "MTU in bounds" is preferred instead of "Check MTU in bounds"
- diagnostic (optional): Provides further contextual information that may help
with determining the source of the validation or provide further details.
Health Check API
----------------
Each Airship component shall expose an endpoint that allows other components
to access and validate its health status. Clients of the health check should
wait up to 30 seconds for a health check response from each component.
GET /v1.0/health
~~~~~~~~~~~~~~~~
Invokes an Airship component to return its health status. This endpoint is
intended to be unauthenticated, and must not return any information beyond the
noted 204 or 503 status response. The component invoked is expected to return a
response in less than 30 seconds.
Health Check Output
^^^^^^^^^^^^^^^^^^^
The current design will be for the component to return an empty response
to show that it is alive and healthy. This means that the component that
is performing the query will receive HTTP response code 204.
HTTP response code 503 with a generic response status or an empty message body
will be returned if the component determines it is in a non-healthy state,
or is unable to reach another component it is dependent upon.
GET /v1.0/health/extended
~~~~~~~~~~~~~~~~~~~~~~~~~
Airship components may provide an extended health check. This request invokes a
component to return its detailed health status. Authentication is required
to invoke this API call.
Extended Health Check Output
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The output structure reuses the Kubernetes Status kind to represent the health
check results. The Status kind will be returned for both successful and failed
health checks to ensure consistencies. The message field will contain summary
information related to the results of the health check. Detailed information
of the health check will be provided as well.
Failure message example::
{
"kind": "Status",
"apiVersion": "v1.0",
"metadata": {},
"status": "Failure",
"message": "{{Component Name}} failed to respond",
"reason": "HealthCheck",
"details": {
"errorCount": {{n}},
"messageList": [
{ "message" : "{{Detailed Health Check failure information}}",
"error": true,
"kind": "SimpleMessage" },
...
]
},
"code": 503
}
Success message example::
{
"kind": "Status",
"apiVersion": "v1.0",
"metadata": {},
"status": "Success",
"message": "",
"reason": "HealthCheck",
"details": {
"errorCount": 0,
"messageList": []
},
"code": 200
}
Versions API
------------
Each Airship component shall expose an endpoint that allows other components to
discover its different API versions. This endpoint is not prefixed by /api
or a version.
GET /versions
~~~~~~~~~~~~~
Invokes an Airship component to return its list of API versions. This endpoint
is intended to be unauthenticated, and must not return any information beyond
the output noted below.
Versions output
^^^^^^^^^^^^^^^
Each Airship component shall return a list of its different API versions. The
response body shall be keyed with the name of each API version, with
accompanying information pertaining to the version's `path` and `status`. The
`status` field shall be an enum which accepts the values `stable` and `beta`,
where `stable` implies a stable API and `beta` implies an under-development
API.
Success message example::
{
"v1.0": {
"path": "/api/v1.0",
"status": "stable"
},
"v1.1": {
"path": "/api/v1.1",
"status": "beta"
},
"code": 200
}
.. _Kubernetes standard for error representation: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#response-status-kind
.. _HTTP status code: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

354
doc/source/develop/code-conventions.rst

@ -1,354 +0,0 @@
..
Copyright 2017 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _code-conventions:
Code and Project Conventions
============================
Conventions and standards that guide the development and arrangement of Airship
component projects.
Project Structure
-----------------
Charts
~~~~~~
Each project that maintains helm charts will keep those charts in a directory
``charts`` located at the root of the project. The charts directory will
contain subdirectories for each of the charts maintained as part of that
project. These subdirectories should be named for the component represented by
that chart.
E.g.: For project ``foo``, which also maintains the charts for ``bar`` and
``baz``:
- foo/charts/foo contains the chart for ``foo``
- foo/charts/bar contains the chart for ``bar``
- foo/charts/baz contains the chart for ``baz``
Helm charts utilize the `helm-toolkit`_ supported by the `Openstack-Helm`_ team
and follow the standards documented there.
Images
~~~~~~
Each project that creates `Docker`_ images will keep Dockerfiles in a
directory ``images`` located at the root of the project. The images directory
will contain subdirectories for each of the images created as part of that
project. The subdirectory will contain Dockerfiles that can be used to
generate images.
E.g.: For project ``foo``, which also produces a Docker image for ``bar``:
- foo/images/foo contains Dockerfiles for ``foo``
- foo/images/bar contains Dockerfiles for ``bar``
Each image must include the following set of labels conforming to the
`OCI image annotations standard`_ as the minimum:
::
org.opencontainers.image.authors='airship-discuss@lists.airshipit.org, irc://#airshipit@freenode'
org.opencontainers.image.url='https://airshipit.org'
org.opencontainers.image.documentation='<documentation on readthedocs or in repository URL>'
org.opencontainers.image.source='<repository URL>'
org.opencontainers.image.vendor='The Airship Authors'
org.opencontainers.image.licenses='Apache-2.0'
org.opencontainers.image.revision='<Git commit ID>'
org.opencontainers.image.created='UTC date and time in RFC3339 format with seconds'
org.opencontainers.image.title='<image name, e.g. "armada">'
Last three annotations (revision, created and title), being dynamic, are
added on a container build stage. Others are statically defined in
Dockerfiles. Optional custom ``org.airshipit.build=community`` annotation is
added to the Airship images published to the community.
Image tags must follow format:
- ``:<full Git commit ID>_<distro_suffix>``
- ``:<branch>_<distro_suffix>`` - latest image built from specific branch
- ``:latest_<distro_suffix>`` - latest image built from master
The ``_<distro suffix>`` (e.g. ``_ubuntu_xenial``) could be omitted. See
`Airship Multiple Linux Distribution Support`_ specification for details.
Images should follow best practices for the container images. Be slim and
secure in particular.
Dockerfile
~~~~~~~~~~
Dockerfile file names must follow format: ``Dockerfile.<distro_suffix>``, where
``<distro_suffix>`` matches corresponding image tag suffix. The
``.<distro_suffix>`` could be omitted where not relevant.
Lines should be indented by a space character next to the Dockerfile
instruction block they correspond to.
Dockerfile must allow base image substitution via ``FROM`` argument. This is
to allow the use of base images stored in third-party or internal repositories.
Dockerfile should follow best practices. Use multistage container builds where
possible to reduce image size and attack surface. ``RUN`` statements should
pass linting via ``shellcheck``. You may use available Dockerfile linters, if
you wish to do so.
See `example Dockerfile`_ file for reference.
Makefile
~~~~~~~~
Each project must provide a Makefile at the root of the project. The Makefile
should implement each of the following Makefile targets:
- ``images`` will produce the docker images for the component and each other
component it is responsible for building.
- ``charts`` will helm package all of the charts maintained as part of the
project.
- ``lint`` will perform code linting for the code and chart linting for the
charts maintained as part of the project, as well as any other reasonable
linting activity.
- ``dry-run`` will produce a helm template for the charts maintained as part
of the project.
- ``all`` will run the lint, charts, and images targets.
- ``docs`` should render any documentation that has build steps.
- ``run_{component_name}`` should build the image and do a rudimentary (at
least) test of the image's functionality.
- ``run_images`` performs the inidividual run_{component_name} targets for
projects that produce more than one image.
- ``tests`` to invoke linting tests (e.g. PEP-8) and unit tests for the
components in the project
- ``format`` to invoke automated code formatting specific to the project's
code language (e.g. Python for armada and Go for airshipctl) as listed
in the Linting and Formatting Standards.
For projects that are Python based, the Makefile targets typically reference
tox commands, and those projects will include a tox.ini defining the tox
targets. Note that tox.ini files will reside inside the source directories for
modules within the project, but a top-level tox.ini may exist at the root of
the repository that includes the necessary targets to build documentation.
Documentation
~~~~~~~~~~~~~
Also see :ref:`documentation-conventions`.
Documentation source for the component should reside in a 'docs' directory at
the root of the project.
Linting and Formatting Standards
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Code in the Airship components should follow the prevalent linting and
formatting standards for the language being implemented. In lieu of industry
accepted code formatting standards for a target language, strive for
readability and maintainability.
=============== ======================================
Known Standards
-------------------------------------------------------
Language Tools Used
=============== ======================================
Ansible ansible-lint
Bash Shellcheck
Go gofmt
Markdown markdownlint
Python YAPF, Flake8
=============== ======================================
Ansible formatting
~~~~~~~~~~~~~~~~~~
Ansible code should be linted to be conformant to the standards checked
by `ansible-lint`_ project.
Bash Formatting
~~~~~~~~~~~~~~~
Bash shell scripts code should be linted to be conformant to the standards
checked by `Shellcheck`_ project.
Bash shell scripts code in Helm templates should ideally be linted as well,
however gating of it is a noble goal and is only desired.
Go Formatting
~~~~~~~~~~~~~
Go code should be formatted using gofmt. When using gofmt be sure to use the
-s flag to include simplification of code for example::
gofmt -s /path/to/file.go
Markdown Formatting
~~~~~~~~~~~~~~~~~~~
Markdown code (documentation) should be linted to be conformant to the
standards checked by `markdownlint`_ project.
Python PEP-8 Formatting
~~~~~~~~~~~~~~~~~~~~~~~
Python should be formatted via YAPF. The knobs for YAPF can be specified in
the project's root directory in '.style.yapf'. The contents of this file should
be::
[style]
based_on_style = pep8
spaces_before_comment = 2
column_limit = 79
blank_line_before_nested_class_or_def = false
blank_line_before_module_docstring = true
split_before_logical_operator = true
split_before_first_argument = true
allow_split_before_dict_value = false
split_before_arithmetic_operator = true
A sample Flake8 section is below, for use in tox.ini, and is the
method of enforcing import orders via Flake8 extension
flake8-import-order::
[flake8]
filename = *.py
show-source = true
# [H106] Don't put vim configuration in source files.
# [H201] No 'except:' at least use 'except Exception:'
# [H904] Delay string interpolations at logging calls.
enable-extensions = H106,H201,H904
# [W503] line break before binary operator
ignore = W503
exclude=.venv,.git,.tox,build,dist,*lib/python*,*egg,tools,*.ini,*.po,*.pot
max-complexity = 24
Airship components must provide for automated checking of their formatting
standards, such as the lint step noted above in the Makefile, and in the future
via CI jobs. Components may provide automated reformatting.
YAML Schema
~~~~~~~~~~~
YAML schema defined by Airship should have key names that follow camelCase
naming conventions.
Note that Airship also integrates and consumes a number of projects from
other open source communities, which may have their own style conventions,
and which will therefore be reflected in Airship deployment manifests.
Those fall outside the scope of these Airship guidelines.
Any YAML schema that violate this convention at the time of this writing
(e.g. with snake_case keys) may be either grandfathered in, or converted,
at the development team's discretion.
Tests Location
~~~~~~~~~~~~~~
Tests should be in parallel structures to the related code, unless dictated by
target language ecosystem.
For Python projects, the preferred location for tests is a ``tests`` directory
under the directory for the module. E.g. Tests for module foo:
{root}/src/bin/foo/foo/tests.
An alternataive location is ``tests`` at the root of the project, although this
should only be used if there are not multiple components represented in the
same repository, or if the tests cross the components in the repository.
Each type of test should be in its own subdirectory of tests, to allow for easy
separation. E.g. tests/unit, tests/functional, tests/integration.
Source Code Location
~~~~~~~~~~~~~~~~~~~~
A standard structure for the source code places the source for each module in
a module-named directory under either /src/bin or /src/lib, for executable
modules and shared library modules respectively. Since each module needs its
own setup.py and setup.cfg (python) that lives parallel to the top-level
module (i.e. the package), the directory for the module will contain another
directory named the same.
For example, Project foo, with module foo_service would have a source structure
that is /src/bin/foo_service/foo_service, wherein the __init__.py for the
package resides.
Sample Project Structure (Python)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Project ``foo``, supporting multiple executable modules ``foo_service``,
``foo_cli``, and a shared module ``foo_client`` ::
{root of foo}
|- /doc
| |- /source
| |- requirements.txt
|- /etc
| |- /foo
| |- {sample files}
|- /charts
| |- /foo
| |- /bar
|- /images
| |- /foo
| | |- Dockerfile
| |- /bar
| |- Dockerfile
|- /tools
| |- {scripts/utilities supporting build and test}
|- /src
| |- /bin
| | |- /foo_service
| | | |- /foo_service
| | | | |- __init__.py
| | | | |- {source directories and files}
| | | |- /tests
| | | | |- unit
| | | | |- functional
| | | |- setup.py
| | | |- setup.cfg
| | | |- requirements.txt (and related files)
| | | |- tox.ini
| | |- /foo_cli
| | |- /foo_cli
| | | |- __init__.py
| | | |- {source directories and files}
| | |- /tests
| | | |- unit
| | | |- functional
| | |- setup.py
| | |- setup.cfg
| | |- requirements.txt (and related files)
| | |- tox.ini
| |- /lib
| |- /foo_client
| |- /foo_client
| | |- __init__.py
| | |- {source directories and files}
| |- /tests
| | |- unit
| | |- functional
| |- setup.py
| |- setup.cfg
| |- requirements.txt (and related files)
| |- tox.ini
|- Makefile
|- README (suitable for github consumption)
|- tox.ini (primarily for the build of repository-level docs)
Note that this is a sample structure, and that target languages may preclude
the location of some items (e.g. tests). For those components with language
or ecosystem standards contrary to this structure, ecosystem convention should
prevail.
.. _Docker: https://www.docker.com/
.. _helm-toolkit: https://git.openstack.org/cgit/openstack/openstack-helm-infra/tree/helm-toolkit
.. _Openstack-Helm: https://wiki.openstack.org/wiki/Openstack-helm
.. _ansible-lint: https://github.com/ansible/ansible-lint
.. _markdownlint: https://github.com/DavidAnson/markdownlint
.. _Shellcheck: https://github.com/koalaman/shellcheck
.. _OCI image annotations standard: https://github.com/opencontainers/image-spec/blob/master/annotations.md#annotations
.. _Airship Multiple Linux Distribution Support: https://airship-specs.readthedocs.io/en/latest/specs/1.x/approved/airship_multi_linux_distros.html#container-builds
.. _example Dockerfile: https://opendev.org/airship/docs/src/branch/master/examples/Dockerfile.opensuse_15

51
doc/source/develop/conventions.rst

@ -1,51 +0,0 @@
..
Copyright 2017 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _conventions:
Airship Conventions
===================
Airship components conform to a minimal set of conventions to provide for
reasonable levels of consistency.
Language
--------
While these documents are not an IETF RFC, `RFC 2119`_ provides for useful
language definitions. In this spirit:
- 'must', 'shall', 'will', and 'required' language indicates inflexible rules.
- 'should' and 'recommended' language is expected to be followed but reasonable
exceptions may exist.
- 'may' and 'can' language is intended to be optional, but will provide a
recommended approach if used.
Conventions and Standards
-------------------------
.. toctree::
:maxdepth: 2
:hidden:
api-conventions
code-conventions
crd-conventions
documentation-conventions
issue-tracking-conventions
service-logging-conventions
.. _RFC 2119: https://www.ietf.org/rfc/rfc2119.txt

44
doc/source/develop/crd-conventions.rst

@ -1,44 +0,0 @@
..
Copyright 2019 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _crd-conventions:
CRD Conventions
===============
Airship will use CRDs to enrich the Kubernetes API with Airship-specific
document schema. Airship projects will follow the following conventions
when defining Custom Resource Definitions (CRDs).
Note that Airship integrates and consumes a number of projects from
other open source communities, which may have their own style conventions,
and which will therefore be reflected in Airship deployment manifests.
Those fall outside the scope of these Airship guidelines.
In general, Airship will follow the
`Kubernetes API Conventions`_ when defining CRDs. These cover naming
conventions (such as using camelCase for key names),
expected document structure, HTTP request verbs and status codes,
and behavioral norms.
Exceptions or restrictions from the Kubernetes conventions are specified below;
this list may grow in the future.
* The ``apiGroup`` (and ``apiVersion``) for Airship CRDs will have values
following the convention ``<function>.airshipit.org``.
.. _Kubernetes API Conventions: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md

262
doc/source/develop/developers.rst

@ -1,262 +0,0 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
===============
Getting Started
===============
Thank you for your interest in Airship. Our community is eager to help you
contribute to the success of our project and welcome you as a member of our
community!
We invite you to reach out to us at any time via the `Airship mailing list`_ or
on our `Slack workspace`_.
Welcome aboard!
.. _Airship mailing list: http://lists.airshipit.org
.. _Slack workspace: http://airshipit.org/slack
=====================
Airship 2 Development
=====================
Development is underway on Airship 2: the educated evolution of Airship 1,
designed with our experience using Airship in production. Airship 2 makes the
Airship control plane ephemeral, leverages entrenched upstream projects such as
the `Cluster API`_, `Metal Kubed`_, Kustomize_, and `kubeadm`_, and embraces
Kubernetes Custom Resource Definitions (CRDs). To learn more about the Airship
2.0 evolution, see the `Airship 2 evolution blog series`_.
Each Airship 2 project has its own development guidelines. Join the ongoing Airship 2
development by referencing the `airshipctl`_ or the `airshipui`_ documentation.
.. _airshipctl: https://docs.airshipit.org/airshipctl/developers.html
.. _Airship 2 evolution blog series: https://www.airshipit.org/blog/airship-blog-series-1-evolution-towards-2.0
.. _airshipui: https://docs.airshipit.org/airshipui/developers.html
.. _Cluster API: https://github.com/kubernetes-sigs/cluster-api
.. _kubeadm: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm
.. _Kustomize: https://github.com/kubernetes-sigs/kustomize
.. _Metal Kubed: https://metal3.io
=====================
Airship 1 Development
=====================
Airship 1 is a collection of open source tools that automate cloud provisioning
and management. Airship provides a declarative framework for defining and
managing the life cycle of open infrastructure tools and the underlying
hardware. These tools include OpenStack for virtual machines, Kubernetes for
container orchestration, and MaaS for bare metal, with planned support for
OpenStack Ironic.
Improvements are still made Airship 1 daily, and we welcome additional
contributors. We recommend that new contributors begin by reading the
high-level architecture overview included in our `treasuremap`_ documentation.
The architectural overview introduces each Airship component, their core
responsibilities, and their integration points.
.. _treasuremap: https://docs.airshipit.org/treasuremap
Deep Dive
---------
Each Airship component is accompanied by its own documentation that provides an
extensive overview of the component. With so many components, it can be
challenging to find a starting point.
We recommend the following:
Try an Airship environment
--------------------------
Airship provides two single-node environments for demo and development purpose.
`Airship-in-a-Bottle`_ is a set of reference documents and shell scripts that
stand up a full Airship environment with the execution of a script.
`Airskiff`_ is a light-weight development environment bundled with a set of
deployment scripts that provides a single-node Airship environment. Airskiff
uses minikube to bootstrap Kubernetes, so it does not include Drydock, MaaS, or
Promenade.
Additionally, we provide a reference architecture for easily deploying a
smaller, demo site.
`Airsloop`_ is a fully-authored Airship site that can be quickly deployed as a
baremetal, demo lab.
.. _Airship-in-a-Bottle: https://opendev.org/airship/treasuremap/src/branch/master/tools/deployment/aiab
.. _Airskiff: https://docs.airshipit.org/treasuremap/airskiff.html
.. _Airsloop: https://docs.airshipit.org/treasuremap/airsloop.html
Focus on a component
--------------------
When starting out, focusing on one Airship component allows you to become
intricately familiar with the responsibilities of that component and understand
its function in the Airship integration. Because the components are modeled
after each other, you will also become familiar with the same patterns and
conventions that all Airship components use.
Airship source code lives in the `OpenDev Airship namespace`_. To clone an
Airship project, execute the following, replacing `<component>` with the name
of the Airship component you want to clone.
.. code-block bash::
git clone https://opendev.org/airship/<component>.git
Refer to the component's documentation to get started. A list of each
component's documentation is listed below for reference:
* `Armada`_
* `Deckhand`_
* `Divingbell`_
* `Drydock`_
* `Pegleg`_
* `Promenade`_
* `Shipyard`_
.. _OpenDev Airship namespace: https://opendev.org/airship
.. _Armada: https://airship-armada.readthedocs.io
.. _Deckhand: https://airship-deckhand.readthedocs.io
.. _Divingbell: https://airship-divingbell.readthedocs.io
.. _Drydock: https://airship-drydock.readthedocs.io
.. _Pegleg: https://airship-pegleg.readthedocs.io
.. _Promenade: https://airship-promenade.readthedocs.io
.. _Shipyard: https://airship-shipyard.readthedocs.io
Testing Changes
---------------
Testing of Airship changes can be accomplished several ways:
#. Standalone, single component testing
#. Integration testing
#. Linting, unit, and functional tests/linting
.. note:: Testing changes to charts in Airship repositories is best
accomplished using the integration method describe below.
Standalone Testing
------------------
Standalone testing of Airship components, i.e. using an Airship component as a
Python project, provides the quickest feedback loop of the three methods and
allows developers to make changes on the fly. We recommend testing initial code
changes using this method to see results in real-time.
Each Airship component written in Python has pre-requisites and guides for
running the project in a standalone capacity. Refer to the documentation listed
below.
* `Armada`_
* `Deckhand`_
* `Drydock`_
* `Pegleg`_
* `Promenade`_
* `Shipyard`_
Integration Testing
-------------------
While each Airship component supports individual usage, Airship components
have several integration points that should be exercised after modifying
functionality.
We maintain several environments that encompass these integration points:
#. `Airskiff`_: Integration of Armada, Deckhand, Shipyard, and Pegleg
#. `Airship-in-a-Bottle Multinode`: Full Airship integration
For changes that merely impact software delivery components, exercising a full
Airskiff deployment is often sufficient. Otherwise, we recommend using the
Airship-in-a-Bottle Multinode environment.
Each environment's documentation covers the process required to build and test
component images.
.. _Airskiff: https://docs.airshipit.org/treasuremap/airskiff.html
.. _Airship-in-a-Bottle Multinode: https://opendev.org/airship/treasuremap/src/branch/master/tools/deployment/aiab
Final Checks
------------
Airship projects provide Makefiles to run unit, integration, and functional
tests as well as lint Python code for PEP8 compliance and Helm charts for
successful template rendering. All checks are gated by Zuul before a change can
be merged. For more information on executing these checks, refer to
project-specific documentation.
Third party CI tools, such as Jenkins, report results on Airship-in-a-Bottle
patches. These can be exposed using the "Toggle CI" button in the bottom
left-hand page of any gerrit change.
Pushing code
------------
Airship uses the `OpenDev gerrit`_ for code review. Refer to the `OpenStack
Contributing Guide`_ for a tutorial on submitting changes to Gerrit code
review.
.. _OpenDev gerrit: https://review.opendev.org
.. _OpenStack Contributing Guide: https://docs.openstack.org/horizon/latest/contributor/contributing.html
Next steps
----------
Upon pushing a change to gerrit, Zuul continuous integration will post job
results on your patch. Refer to the job output by clicking on the job itself to
determine if further action is required. If it's not clear why a job failed,
please reach out to a team member in IRC. We are happy to assist!
Assuming all continuous integration jobs succeed, Airship community members and
core developers will review your patch and provide feedback. Many patches are
submitted to Airship projects each day. If your patch does not receive feedback
for several days, please reach out using IRC or the Airship mailing list.
Merging code
------------
Like most OpenDev projects, Airship patches require two +2 code review votes
from core members to merge. Once you have addressed all outstanding feedback,
your change will be merged.
Beyond
------
Congratulations! After your first change merges, please keep up-to-date with
the team. We hold two weekly meetings for project and design discussion:
Our weekly #airshipit IRC meeting provides an opportunity to discuss project
operations.
Our weekly design call provides an opportunity for in-depth discussion of new
and existing Airship features.
For more information on the times of each meeting, refer to the `Airship
wiki`_.
.. _Airship wiki: https://wiki.openstack.org/wiki/Airship

87
doc/source/develop/documentation-conventions.rst

@ -1,87 +0,0 @@
..
Copyright 2017 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _documentation-conventions:
Documentation
=============
Each Airship component will maintain documentation addressing two audiences:
#. Consumer documentation
#. Developer documentation
Consumer Documentation
----------------------
Consumer documentation is that which is intended to be referenced by users of
the component. This includes information about each of the following:
- Introduction - the purpose and charter of the software
- Features - capabilies the software has
- Usage - interaction with the software - e.g. API and CLI documentation
- Setup/Installation - how an end user would set up and run the software
including system requirements
- Support - where and how a user engages support or makes change requests for
the software
Developer Documentation
-----------------------
Developer documentation is used by developers of the software, and addresses
the following topics:
- Archiecture and Design - features and structure of the software
- Inline, Code, Method - documentaiton specific to the fuctions and procedures
in the code
- Development Environment - explaining how a developer would need to configure
a working environment for the software
- Contribution - how a developer can contribute to the software
Format
------
There are multiple means by which consumers and developers will read the
documentation for Airship components. The two common places for Airship
components are `Github`_ in the form of README and code-based documentation,
and `Readthedocs`_ for more complete/formatted documentation.
Documentation that is expected to be read in Github must exist and may use
either `reStructuredText`_ or `Markdown`_. This generally would be limited to
the README file at the root of the project and/or a documentation directory.
The README should direct users to the published documentation location.
Documentation intended for Readthedocs will use reStructuredText, and should
provide a `Sphinx`_ build of the documentation.
Finding Treasuremap
-------------------
`Treasuremap`_ is a project that serves as a starting point for the larger
Containerized Cloud Platform, and provides context for the Airship component
projects.
Airship component projects should include the following at the top of the
main/index page of their `Readthedocs`_ documentation:
.. tip::
{{component name}} is part of Airship, a collection of components that
coordinate to form a means of configuring, deploying and maintaining a
Kubernetes environment using a declarative set of yaml documents. More
details on using Airship may be found by using the `Treasuremap`_
.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html
.. _Markdown: https://daringfireball.net/projects/markdown/syntax
.. _Readthedocs: https://airshipit.readthedocs.io/
.. _Github: https://github.com
.. _Sphinx: http://www.sphinx-doc.org/en/stable/index.html
.. _Treasuremap: https://opendev.org/airship/treasuremap/

144
doc/source/develop/issue-tracking-conventions.rst

@ -1,144 +0,0 @@
..
Copyright 2020 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _issue-tracking-conventions:
Issue Tracking
==============
Issues for the Airship Project are tracked on a per-project basis using Github
Issues. All feature requests and bugs should be submitted to the respective
project's Github Issues board for community evaluation and action. For
additional details on a project's issue tracking workflow, see its
CONTRIBUTING.md file.
Project CONTRIBUTING.md Files:
- `airshipctl CONTRIBUTING.md`_
Submitting Issues
-----------------
Issues can be submitted by navigating to a project's Github Issue page and
selecting "New issue".
Depending on the project, you may be prompted to select an issue
type. These selections are associated with templates to aid in the issue
creation process. If there are no templates associated with the project,
utilize the following templates:
- `Feature Request Template`_
- `Bug Report Template`_
When submitting issues, be descriptive and concise. If the issue is complex
consider breaking it down into smaller issues so it can be more easily
addressed by the community.
Grooming Issues
---------------
Issues are groomed by each project's core reviewers. Depending on how active
the project is and their workflow, it can take up to two weeks for issues to
be groomed. Issues will be marked with the "triage" label until they have been
groomed and prioritized. We encourage developers to not work on issues marked
as "triage" as these issues are not guaranteed to be accepted by the project.
Each project will have a multitude of labels used to help categorize issues and
improve organization. Labels will differ from project to project, but some
common labels may include:
- Process labels ("ready for review", "wip", "blocked", "triage")
- Priority labels ("priority/low", "priority/medium", "priority/high")
- Component labels ("component/engine", "component/cli", etc...)
- Type labels ("feature", "bug", "epic")
As many applicable labels as possible should be applied to issues. These labels
should be consistently reevaluated and updated as the issue evolves.
Issue Lifecycle
---------------
The general lifecycle for issues is as follows:
#. The issue is created by a member of the community on Github Issues. By
default, the issues should have a type label and be labeled as "triage".
Neither the submitter nor any other developer should work on the issue at
this time, but they may discuss it on the Github Issue board to further
clarify the issue.
#. The issue is groomed by members of the core reviewer team for the project,
either on a scheduled grooming call or asynchronously on the Github Issues
board. During the grooming process the core reviewer team will establish
whether the issue is part of the project's scope and what the issue's
priority level is. They will also apply a multitude of labels to help
improve the organization of the issue board and the visibility of the issue.
At the end of the process if the issue is accepted, the "triage" label will
be removed and the issue will be available to be assigned and worked on. It
is possible that the core reviewer team will need additional details. Please
be attentive to updates on created issues to ensure they are addressed in a
timely manner.
#. The issue is assigned to a member of the community to be addressed. Only
core reviewers have the ability to assign issues. If a member of the
community wishes to be assigned to an issue, they should make a comment on
the issue requesting to have it assigned to them. Please only start work on
an issue after it is assigned to you to decrease the risk of duplicate
changes. Issue assignees are encouraged to use process labels to indicate
where they are in the development workflow
(i.e. "wip" or "ready for review"). Consistent updates let the core reviewer
team know that the issue is still active. If no measurable work has been
performed on an assigned issue within two weeks, the issue may be considered
"stale" and the assignee may be removed from the issue.
#. Once a developer completes work on an issue's associated change (or
research), they should indicate that work is complete and
"ready for review". Include a link to the associated change along with any
observations of worth in the issue's comments. Once the change is merged,
the core reviewer team will mark the issue as completed.
Github Issues Bot
~~~~~~~~~~~~~~~~~
To help improve Gerrit and Github integration, Airship utilizes a python daemon
to update Github Issues with Gerrit change details. The utility is hosted on
Github under the name `Gerrit-to-Github-Issues`_. Currently the bot only runs
against the airshipctl project, but it may be implemented later into other
projects.
The bot performs the following functions:
- Comments on issues with the information of active Gerrit changes including
links, review statuses, and author information.
- Updates issue process labels with the "wip" label if "DNM" or "WIP" are
present in the change's commit message and "ready for review" in all other
cases.
To leverage the bot's full functionality, be sure to include a reference for the
issue you are addressing from GitHub Issues inside the change commit message.
There are three ways of doing this:
#. Add a statement in your commit message in the format of ``Relates-To: #X``.
This will add a link on issue "#X" to your change.
#. Add a statement in your commit message in the format of ``Closes: #X``.
This will add a link on issue "#X" to your change and will close the issue when
your change merges.
#. Add a bracketed tag at the beginning of your commit message in the format of
``[#X] <begin commit message>``. This will add a link on issue "#X" to your
change. This method is considered a fallback in lieu of the other two methods.
Any issue references should be evaluated within 15 minutes of being uploaded.
For any questions, comments, or requests please reach out to Ian Pittwood
either at ian-pittwood on the Airship IRC/Slack or at pittwoodian@gmail.com.
.. _airshipctl Issue Tracker: https://github.com/airshipit/airshipctl/issues
.. _airshipctl CONTRIBUTING.md: https://opendev.org/airship/airshipctl/src/branch/master/CONTRIBUTING.md
.. _Feature Request Template: https://opendev.org/airship/docs/raw/branch/master/doc/source/develop/issue_templates/feature_request.md
.. _Bug Report Template: https://opendev.org/airship/docs/raw/branch/master/doc/source/develop/issue_templates/bug_report.md
.. _Gerrit-to-Github-Issues: https://github.com/ianpittwood/Gerrit-to-Github-Issues

9
doc/source/develop/issue_templates/bug_report.md

@ -1,9 +0,0 @@
**Problem description (if applicable)**
A description of the problem or background information that illustrates the need
for a new feature.
**Proposed change**
A detailed description of the new, requested behavior.
**Potential impacts**
Potential security or performance related impacts.

9
doc/source/develop/issue_templates/feature_request.md

@ -1,9 +0,0 @@
**Problem description (if applicable)**
A description of the problem or background information that illustrates the need
for a new feature.
**Proposed change**
A detailed description of the new, requested behavior.
**Potential impacts**
Potential security or performance related impacts.

65
doc/source/develop/service-logging-conventions.rst

@ -1,65 +0,0 @@
..
Copyright 2017 AT&T Intellectual Property.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _service-logging-conventions:
Service Logging Conventions
===========================
Airship services must provide logging, should conform to a standard logging
format, and may utilize shared code to do so.
Standard Logging Format
-----------------------
The following is the intended format to be used when logging from Airship
services. When logging from those parts that are no services, a close
reasonable approximation is desired.
::
Timestamp Level RequestID ExternalContextID ModuleName(Line) Function - Message
Where:
- Timestamp is like ``2006-02-08 22:20:02,165``, or the standard ouptut from
``%(asctime)s``
- Level is 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', padded to 8
characters, left aligned.
- RequestID is the UUID assigned to the request in canonical 8-4-4-4-12 format.
- ExternalContextID is the UUID assigned from the external source (or generated
for the same purpose), in 8-4-4-4-12 format.
- ModuleName is the name of the module or class from which the logging
originates.
- Line is the line number of the logging statement
- Function is the name of the function or method from which the logging
originates
- Message is the text of the message to be logged.
Example Python Logging Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
%(asctime)s %(levelname)-8s %(req_id)s %(external_ctx)s %(user)s %(module)s(%(lineno)d) %(funcName)s - %(message)s'
See `Python Logging`_ for explanation of format.
Loggers in Code
---------------
Components should prefer loggers that are at the module or class level,
allowing for finer grained logging control than a global logger.
.. _Python Logging: https://docs.python.org/3/library/logging.html

49
doc/source/index.rst

@ -1,5 +1,5 @@
..
Copyright 2017-2020 AT&T Intellectual Property.
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -14,9 +14,9 @@
License for the specific language governing permissions and limitations
under the License.
=================================
Welcome to Airship documentation!
=================================
===================================
Welcome to Airship 2 documentation!
===================================
Airship is a collection of components that declaratively configure, deploy
and maintain a `Kubernetes`_ environment defined by `YAML`_ documents. Airship
@ -29,39 +29,22 @@ is supported by the `OpenStack Foundation`_.
About this Documentation
========================
Airship documentation serves the entire community with resources for users and
developers.
This Airship 2 documentation in v2.0.0 branch currently serves as a draft only.
.. toctree::
:caption: Learn About Airship
:caption: Airship 2
:maxdepth: 1
What is Airship? <https://www.airshipit.org/collateral/Airship_OnePager.pdf>
learn/vulnerabilities.rst
.. toctree::
:caption: Try Airship
:maxdepth: 1
Airship-in-a-Bottle <https://opendev.org/airship/treasuremap/src/branch/master/tools/deployment/aiab>
Airsloop: Simple Bare-Metal Airship <https://docs.airshipit.org/treasuremap/airsloop.html>
Seaworthy: Production-grade Airship <https://docs.airshipit.org/treasuremap/seaworthy.html>
.. toctree::
:caption: Develop Airship
:maxdepth: 1
develop/developers.rst
develop/conventions.rst
.. toctree::
:caption: Airship Project Documentation
:maxdepth: 1
Airship Documentation <https://docs.airshipit.org>
Airshipctl <https://docs.airshipit.org/airshipctl>
Airshipui <https://docs.airshipit.org/airshipui>
Treasuremap <https://docs.airshipit.org/treasuremap>
airship2/basics.rst
airship2/try.rst
airship2/production.rst
airship2/howto.rst
airship2/release-notes.rst
airship2/training.rst
airship2/contributing.rst
airship2/reference.rst
airship2/architecture.rst
airship2/other.rst
learn/glossary.rst
Other Resources

2
doc/source/learn/glossary.rst

@ -1,5 +1,5 @@
..
Copyright 2017-2020 AT&T Intellectual Property.
Copyright 2020-2021 The Airship authors.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may

70
doc/source/learn/vulnerabilities.rst

@ -1,70 +0,0 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _vulnerabilities:
Airship Security Vulnerability Management
=========================================
The Airship community is committed to expediently confirming, resolving, and
disclosing all reported security vulnerabilities. We appreciate your
cooperation and participation in our vulnerability management process outlined
below.
Report a Vulnerability
----------------------
If you discover a vulnerability in an Airship project, please treat the issue
with a sense of confidentiality and disclose it to the `airship-security
mailing list`_:
airship-security@lists.airshipit.org
Additionally, please include any potential fixes, as doing so can expedite the
disclosure and patching processes.
The Airship Working Committee is the sole subscriber of the `airship-security
mailing list`_ and monitors it for reported vulnerabilities. The committee
confirms or rejects reported vulnerabilities in correspondence with the
vulnerability reporter. In the event that the Airship Working Committee does
not have the expertise or availability to resolve a reported vulnerability, the
committee may solicit assistance from outside contributors to better facilitate
the understanding and resolution of reported security vulnerabilities.
Receive Early Disclosures
-------------------------
We prefer to disclose confirmed security vulnerabilities as soon as possible.
While circumstances may not always allow immediate disclosure, vulnerabilities
may be disclosed over the `airship-embargo-notice mailing list`_ when a fix
becomes available. The airship-embargo-notice mailing list notifies Airship
users of confirmed vulnerabilities. If you operate Airship in a production
environment, we recommend subscribing to the `airship-embargo-notice mailing
list`_ by contacting the Airship Working Committee. The Airship Working
Committee evaluates subscription requests on a case-by-case basis.
Receive Public Disclosures
--------------------------
Within ninety days of the initial vulnerability report, except in unusual
circumstances, the Airship Working Committee will publicly disclose the
reported vulnerability and its mitigation over the `airship-announce`_ and
`airship-discuss`_ mailing lists. If a fix merges before the aforementioned
ninety day period expires, the Airship Working Committee will instead disclose
the vulnerability and fix twenty-one days later. We recommend subscribing to
both mailing lists in order to receive security updates.
.. _airship-security mailing list: http://lists.airshipit.org/cgi-bin/mailman/listinfo/airship-security
.. _airship-embargo-notice mailing list: http://lists.airshipit.org/cgi-bin/mailman/listinfo/airship-embargo-notice
.. _airship-announce: http://lists.airshipit.org/cgi-bin/mailman/listinfo/airship-announce
.. _airship-discuss: http://lists.airshipit.org/cgi-bin/mailman/listinfo/airship-discuss