starlingx/specs
Code Issues Proposed changes

Add doc8 linter to tox for spec validation

Browse Source 
This will check the specs for the following when running tox:

linters runtests: commands[1] | doc8 specs/
Scanning...
Validating...
========
Total files scanned = 7
Total files ignored = 0
Total accumulated errors = 0
Detailed error counts:
    - CheckCarriageReturn = 0
    - CheckIndentationNoTab = 0
    - CheckMaxLineLength = 0
    - CheckNewlineEndOfFile = 0
    - CheckTrailingWhitespace = 0
    - CheckValidity = 0

Also fixes:
 - One long line violation in instructions.rst
 - DOS CRLF formatting of
   containerization-2002840-local-docker-registry.rst

Change-Id: I73e1c87401156fe1fd52ab2b5460201f559c6284
Signed-off-by: Robert Church <robert.church@windriver.com>
This commit is contained in:
Robert Church 2018-10-17 12:26:33 -04:00
parent 606c09eab8
commit f2a756f493
4 changed files with 172 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

326
specs/2019.03/approved/containerization-2002840-local-docker-registry.rst
View File

@ -1,163 +1,163 @@
.. This work is licensed under a Creative Commons Attribution 3.0 Unported .. This work is licensed under a Creative Commons Attribution 3.0 Unported
License. License.
http://creativecommons.org/licenses/by/3.0/legalcode http://creativecommons.org/licenses/by/3.0/legalcode
===================== =====================
Local Docker Registry Local Docker Registry
===================== =====================
Storyboard: https://storyboard.openstack.org/#!/story/2002840 Storyboard: https://storyboard.openstack.org/#!/story/2002840
A local Docker registry should be included in a StarlingX containerized A local Docker registry should be included in a StarlingX containerized
deployment to allow users to store Docker images that they might not want deployment to allow users to store Docker images that they might not want
to share publicly through Docker Hub. to share publicly through Docker Hub.
Problem Description Problem Description
=================== ===================
Without the local Docker registry, the only way to obtain Docker images is Without the local Docker registry, the only way to obtain Docker images is
through public means, such as Docker Hub. Users of StarlingX might have images through public means, such as Docker Hub. Users of StarlingX might have images
that they do not want to publicly share. Docker Hub might also not meet the that they do not want to publicly share. Docker Hub might also not meet the
users' performance requirements. Deploying a local Docker registry allows the users' performance requirements. Deploying a local Docker registry allows the
user to deploy custom images without uploading it to Docker Hub first. user to deploy custom images without uploading it to Docker Hub first.
Use Cases Use Cases
========= =========
End users and StarlingX administrators can push and deploy images from the End users and StarlingX administrators can push and deploy images from the
local registry without publicly sharing them on Docker Hub. local registry without publicly sharing them on Docker Hub.
Proposed change Proposed change
=============== ===============
An instance of the Docker Distribution project would be integrated on An instance of the Docker Distribution project would be integrated on
StarlingX: StarlingX:
https://github.com/docker/distribution https://github.com/docker/distribution
Docker Distribution (Docker Registry) shall be deployed in StarlingX, managed Docker Distribution (Docker Registry) shall be deployed in StarlingX, managed
by STX-HA's SM in active standby mode. The registry process shall be running by STX-HA's SM in active standby mode. The registry process shall be running
as a host process as opposed to a container. Docker Distribution shall use a as a host process as opposed to a container. Docker Distribution shall use a
resizable DRBD synced file system as its root directory. resizable DRBD synced file system as its root directory.
The registry will be deployed with token authentication. A token server shall The registry will be deployed with token authentication. A token server shall
be deployed as well, and managed by SM, running in active standby mode. The be deployed as well, and managed by SM, running in active standby mode. The
token server will use Openstack Keystone as a back end, and allow users to log token server will use Openstack Keystone as a back end, and allow users to log
in using their Openstack credentials to work with Docker images in the in using their Openstack credentials to work with Docker images in the
registry. The token server shall provide minimal authorization support where registry. The token server shall provide minimal authorization support where
users shall only be allowed to modify resources belonging to their own repo. users shall only be allowed to modify resources belonging to their own repo.
For example, user1 shall not be allowed to push user2/testimage:v1.0. For example, user1 shall not be allowed to push user2/testimage:v1.0.
Alternatives Alternatives
============ ============
Docker registry shall be deployed as a host process as opposed to a container. Docker registry shall be deployed as a host process as opposed to a container.
This allows the registry to hold kube-system container images for starting up This allows the registry to hold kube-system container images for starting up
Kubernetes itself in the future if needed. Kubernetes itself in the future if needed.
Data model impact Data model impact
================= =================
None None
REST API impact REST API impact
=============== ===============
None None
Security impact Security impact
=============== ===============
Docker registry shall run on port 9001 while the registry token server shall Docker registry shall run on port 9001 while the registry token server shall
run on port 9002. Authentication and authorization are done through Keystone, run on port 9002. Authentication and authorization are done through Keystone,
so no credentials need to be stored on the Docker registry or token server so no credentials need to be stored on the Docker registry or token server
side. Communications between the registry, Docker client, and registry token side. Communications between the registry, Docker client, and registry token
server will be through HTTPS by default, using the system self-signed server will be through HTTPS by default, using the system self-signed
certificate by default. All communication is done over the management network. certificate by default. All communication is done over the management network.
Other end user impact Other end user impact
===================== =====================
None None
Performance Impact Performance Impact
================== ==================
None None
Other deployer impact Other deployer impact
===================== =====================
None None
Developer impact Developer impact
================= =================
None None
Upgrade impact Upgrade impact
=============== ===============
None None
Implementation Implementation
============== ==============
Assignee(s) Assignee(s)
=========== ===========
Primary assignee: Primary assignee:
jerry-sun-u jerry-sun-u
Repos Impacted Repos Impacted
============== ==============
* stx-integ * stx-integ
* stx-config * stx-config
* stx-ha * stx-ha
Work Items Work Items
=========== ===========
Build, configure, and manage through STX-HA's SM, the Docker registry process. Build, configure, and manage through STX-HA's SM, the Docker registry process.
Build, configure, and manage through SM, a token server that can communicate Build, configure, and manage through SM, a token server that can communicate
with Openstack Keystone and can act as an authentication and authorization with Openstack Keystone and can act as an authentication and authorization
service for the Docker registry. service for the Docker registry.
Dependencies Dependencies
============ ============
Docker Distribution and its dependencies Docker Distribution and its dependencies
SM from stx-ha SM from stx-ha
Testing Testing
======= =======
Docker Distribution comes with its own unit tests. The token server can be Docker Distribution comes with its own unit tests. The token server can be
tested by doing a deployment on StarlingX. Specifically, ensure that one tested by doing a deployment on StarlingX. Specifically, ensure that one
user cannot delete images from another user. user cannot delete images from another user.
For now, Docker registry and token server processes should be run only if For now, Docker registry and token server processes should be run only if
kubernetes is configured during config controller. kubernetes is configured during config controller.
Documentation Impact Documentation Impact
==================== ====================
None None
References References
========== ==========
None None
History History
======= =======
.. list-table:: Revisions .. list-table:: Revisions
:header-rows: 1 :header-rows: 1
* - Release Name * - Release Name
- Description - Description
* - 2019.03 * - 2019.03
- Introduced - Introduced

14
specs/instructions.rst
View File

@ -34,13 +34,13 @@ encouraged to use index entries for their documents to help with discovery.
Naming Naming
------ ------
Document naming standards help readers find specs. For the StarlingX repository, Document naming standards help readers find specs. For the StarlingX
the following document naming is recommended. The categories listed here are repository, the following document naming is recommended. The categories listed
likely incomplete, and may need expansion to cover new cases. It is preferrable here are likely incomplete, and may need expansion to cover new cases. It is
to deviate (and hopefully amend the list) than force document names into preferrable to deviate (and hopefully amend the list) than force document names
nonsense categories. Prefer using categories that have previously been used or into nonsense categories. Prefer using categories that have previously been
that are listed here over new categories, but don't force the category into used or that are listed here over new categories, but don't force the category
something that doesn't make sense. into something that doesn't make sense.
Document names should follow a pattern as follows:: Document names should follow a pattern as follows::

1
test-requirements.txt
View File

@ -1,2 +1,3 @@
PyYAML>=3.1.0 PyYAML>=3.1.0
yamllint>=0.5.2 yamllint>=0.5.2
doc8

1
tox.ini
View File

@ -24,6 +24,7 @@ commands =
\( -name .tox -prune \) \ \( -name .tox -prune \) \
-o -type f -name '*.yaml' \ -o -type f -name '*.yaml' \
-print0 | xargs -0 yamllint" -print0 | xargs -0 yamllint"
doc8 specs/
[testenv:venv] [testenv:venv]
commands = {posargs} commands = {posargs}