Permalink
Browse files

isutton/docs-scaffold (#53)

* docs: initial commit

* docs: add deployment.rst

* docs: more docs

* docs: more docs

* docs: more docs

* docs: clean docs

* docs: more docs

* docs: Add Dockerfile for documentation builder

* docs/application: explain what happens when an application object is created

* docs: add more information in Application's "Scope of control" section

* docs: add more Release docs

* docs: expand InstallationTarget concept documentation

* docs: re-touch intro

* docs: api reference draft

* docs: add quick install guide

The start/concepts bits were mostly replaced by the API reference docs.

There's more there that isn't covered, mostly pertaining to
architecture, which still needs to find a home.

* ci: build release tagged images

* docs: start fleshing out administrator's guide

This involved moving application developer docs out of 'operations' to
'user'.
  • Loading branch information...
isutton authored and kanatohodets committed Dec 8, 2018
1 parent da6ebba commit d7530c6e6aa87f96b0e3c098c1cd3ffe077599ee
Showing with 2,005 additions and 0 deletions.
  1. +1 −0 .gitignore
  2. +9 −0 ci/package.sh
  3. +7 −0 docs/Dockerfile
  4. +13 −0 docs/_static/theme_overrides.css
  5. +12 −0 docs/about_docs.rst
  6. +81 −0 docs/api-reference/administrator/cluster.rst
  7. +13 −0 docs/api-reference/administrator/index.rst
  8. +11 −0 docs/api-reference/index.rst
  9. +130 −0 docs/api-reference/plumbing/capacity-target.rst
  10. +19 −0 docs/api-reference/plumbing/index.rst
  11. +144 −0 docs/api-reference/plumbing/installation-target.rst
  12. +138 −0 docs/api-reference/plumbing/traffic-target.rst
  13. +175 −0 docs/api-reference/porcelain/application.rst
  14. +14 −0 docs/api-reference/porcelain/index.rst
  15. +181 −0 docs/api-reference/porcelain/release.rst
  16. +4 −0 docs/build.sh
  17. +23 −0 docs/conf.py
  18. +37 −0 docs/examples/application-minimal.yaml
  19. +42 −0 docs/examples/application.yaml
  20. +34 −0 docs/examples/capacitytarget.yaml
  21. +15 −0 docs/examples/cluster.yaml
  22. +29 −0 docs/examples/installationtarget.yaml
  23. +80 −0 docs/examples/release.yaml
  24. +34 −0 docs/examples/traffictarget.yaml
  25. +12 −0 docs/index.rst
  26. +28 −0 docs/install/building.rst
  27. +10 −0 docs/install/install.rst
  28. +9 −0 docs/install/installing.rst
  29. +6 −0 docs/intro/getting_help.rst
  30. +10 −0 docs/intro/index.rst
  31. +101 −0 docs/intro/shipper.rst
  32. +58 −0 docs/operations/cluster-architecture.rst
  33. +4 −0 docs/operations/fleet-management.rst
  34. +15 −0 docs/operations/index.rst
  35. +4 −0 docs/operations/monitoring.rst
  36. +8 −0 docs/operations/shipperctl.rst
  37. +4 −0 docs/requirements.txt
  38. +125 −0 docs/start/install.rst
  39. +6 −0 docs/user/cicd.rst
  40. +120 −0 docs/user/deployment.rst
  41. +11 −0 docs/user/index.rst
  42. +228 −0 docs/user/troubleshooting.rst
@@ -4,3 +4,4 @@ e2e.test
.vscode/
pkg/chart/testdata/chartmuseum
pkg/chart/testdata/index.yaml
docs/generated
@@ -25,6 +25,15 @@ docker push bookingcom/shipper:$TRAVIS_COMMIT
docker build -t bookingcom/shipper-state-metrics:$TRAVIS_COMMIT -f Dockerfile.metrics .
docker push bookingcom/shipper-state-metrics:$TRAVIS_COMMIT

# building a tagged release
if [ "$TRAVIS_BRANCH" == "$TRAVIS_TAG" ]; then
docker tag bookingcom/shipper-state-metrics:$TRAVIS_COMMIT bookingcom/shipper-state-metrics:$TRAVIS_TAG
docker push bookingcom/shipper-state-metrics:$TRAVIS_TAG

docker tag bookingcom/shipper:$TRAVIS_COMMIT bookingcom/shipper:$TRAVIS_TAG
docker push bookingcom/shipper:$TRAVIS_TAG
fi

docker logout

unset DOCKER_USERNAME
@@ -0,0 +1,7 @@
FROM python:3

RUN echo $HTTP_PROXY $HTTPS_PROXY
WORKDIR /usr/src/app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
CMD [ "sphinx-autobuild", "--host", "0.0.0.0", "-W", "-b", "html", ".", "generated" ]
@@ -0,0 +1,13 @@
/* override table width restrictions */
@media screen and (min-width: 767px) {

.wy-table-responsive table td {
/* !important prevents the common CSS stylesheets from overriding
this as on RTD they are loaded after this stylesheet */
white-space: normal !important;
}

.wy-table-responsive {
overflow: visible !important;
}
}
@@ -0,0 +1,12 @@
Documentation overview
=======================

* :ref:`Introduction <intro>`: Brief overview of what Shipper is and why you might be interested

* :ref:`Quick start <start>`: 5 minutes to a working Shipper setup

* :ref:`User guide <user>`: Using Shipper to deploy your code

* :ref:`Administrator guide <operations>`: Production installation, monitoring, and cluster fleet management

* :ref:`API Reference <api-reference>`: Detailed reference on the Shipper resources
@@ -0,0 +1,81 @@
.. _api-reference_cluster:

#######
Cluster
#######

A *Cluster* object represents a Kubernetes cluster that Shipper can deploy to.
It is an **administrative** interface.

They serve two purposes:

* Enable Shipper to connect to the cluster to manage it
* Enable administrators to influence how *Releases* are scheduled to this cluster.

The second point allows administrators to perform tasks like load balancing
workloads between clusters, shift workloads from one cluster to another, or
drain clusters for risky maintenance. For examples of these tasks, see the
:ref:`administrator's guide <operations_fleet-management>`.

*******
Example
*******

.. literalinclude:: ../../examples/cluster.yaml
:language: yaml
:linenos:

****
Spec
****

``.spec.apiMaster``
===================

``apiMaster`` is the URL of the Kubernetes cluster API server. Shipper uses
this to connect to the cluster to manage it. This is the same URL as in
a ``~/.kube/config`` for enabling ``kubectl`` commands.

.. _api-reference_cluster_capabilities:

``.spec.capabilities``
======================

``capabilities[]`` is a required field that lists the capabilities the
cluster has. Capabilities are arbitrary tags that can be used by Application
objects to select clusters while rolling out. For example, one Kubernetes
cluster might have nodes provisioned with GPUs for video encoding. Adding 'gpu'
as a Cluster capability will allow application developers to specify 'gpu' in
their set of Application ``clusterRequirements`` if their application needs
access to that feature.

``.spec.region``
================

``region`` is a required field that specifies the region the cluster belongs to.

``.spec.scheduler``
===================

``scheduler.unschedulable`` is an optional field that causes clusters to
be ignored during rollout cluster selection. This allows operators to mark
clusters to be drained. Default: ``false``.

``scheduler.weight`` is an optional field that assigns a weight to the
cluster. The weight influences the priority of the cluster during rollout
cluster selection. Default: ``100``.

``scheduler.identity`` is an optional field that assigns an identity to
the cluster different than its ``.metadata.name`` value. This allows operators
to make one cluster 'impersonate' another in order to transfer all of the
Applications on one cluster to another specific cluster. Default:
``.metadata.name``.

More information on how to use these fields to manage a fleet of clusters can
be found in the :ref:`Administrator's guide <operations_fleet-management>`.

******
Status
******

Cluster objects do not currently have a meaningful ``.status`` field.
@@ -0,0 +1,13 @@
.. _api-reference_administrator:

Administrator APIs
====================

These objects represent internal details of a Shipper installation. They expose
tools for administrators to configure Shipper or change how Shipper works for
application developers.

.. toctree::
:maxdepth: 2

cluster
@@ -0,0 +1,11 @@
.. _api-reference:

API Reference
=============

.. toctree::
:maxdepth: 2

porcelain/index
plumbing/index
administrator/index
@@ -0,0 +1,130 @@
.. _api-reference_capacity-target:

###############
Capacity Target
###############

A *CapacityTarget* is the interface used by the Strategy Controller to change
the target number of replicas for an application in a set of clusters. It is
acted upon by the Capacity Controller.

The ``status`` resource includes status per-cluster so that the Strategy
Controller can determine when the Capacity Controller is complete and it can
move to the traffic step.

*******
Example
*******

.. literalinclude:: ../../examples/capacitytarget.yaml
:language: yaml
:linenos:

****
Spec
****

``.spec.clusters``
===================

``clusters`` is a list of clusters the associated *Release* object is present
in. Each item in the list has a ``name``, which should map to a :ref:`Cluster
<api-reference_cluster>` object, and a ``percent``. ``percent`` declares how
much capacity the *Release* should have in this cluster relative to the final
replica count. For example, if the final replica count is 10 and the
``percent`` is 50, the Deployment object for this *Release* will be patched to
have 5 pods.

.. literalinclude:: ../../examples/capacitytarget.yaml
:language: yaml
:lines: 9-14
:linenos:

******
Status
******

``.status.clusters``
====================

``.status.clusters`` is a list of objects representing the capacity status
of all clusters where the associated Release objects must be installed.

.. literalinclude:: ../../examples/capacitytarget.yaml
:language: yaml
:lines: 15-
:linenos:

The following table displays the keys a cluster status entry should have:

.. list-table::
:widths: 1 99
:header-rows: 1

* - Key
- Description
* - **name**
- The Application Cluster name. For example, **kube-us-east1-a**.
* - **availableReplicas**
- The number of pods that have successfully started up
* - **achievedPercent**
- What percentage of the final replica count does **availableReplicas**
represent.
* - **sadPods**
- Pod Statuses for up to 5 Pods which are not yet Ready.
* - **conditions**
- A list of all conditions observed for this particular Application Cluster.

``.status.clusters.conditions``
===============================

The following table displays the different conditions statuses and reasons reported in the
*CapacityTarget* object for the **Operational** condition type:

.. list-table::
:widths: 1 1 1 99
:header-rows: 1

* - Type
- Status
- Reason
- Description
* - Operational
- True
- N/A
- Cluster is reachable, and seems to be operational.
* - Operational
- False
- ServerError
- Some error has happened Shipper couldn't classify. Details can be
found in the ``.message`` field.

The following table displays the different conditions statuses and reasons reported in the
*CapacityTarget* object for the **Ready** condition type:

.. list-table::
:widths: 1 1 1 99
:header-rows: 1

* - Type
- Status
- Reason
- Description
* - Ready
- True
- N/A
- The correct number of pods are running and all of them are Ready.
* - Ready
- False
- WrongPodCount
- This cluster has not yet achieved the desired number of pods.
* - Ready
- False
- PodsNotReady
- The cluster has the desired number of pods, but not all of them are
Ready.
* - Ready
- False
- MissingDeployment
- Shipper could not find the Deployment object that it expects to be able
to adjust capacity on. See ``message`` for more details.
@@ -0,0 +1,19 @@
.. _api-reference_plumbing:

##############
Low-level APIs
##############

These objects represent low-level commands defining the state of specific
clusters, as well as the current status of those commands. Together they
provide 'just enough federation' to implement Shipper's rollout strategies.

They depend on an associated *Release* object to work correctly: they cannot be
created in isolation.

.. toctree::
:maxdepth: 2

installation-target
capacity-target
traffic-target
Oops, something went wrong.

0 comments on commit d7530c6

Please sign in to comment.