From a0a744fd88b12f662fa3308ecbb4eac32716afc3 Mon Sep 17 00:00:00 2001 From: Bryan Strassner Date: Tue, 13 Mar 2018 17:21:16 -0500 Subject: [PATCH] Documentation for Shipyard deployment-configuration Updates workflow documentation to include information explaining the deployment configuration document used by Shipyard Change-Id: I1062958f51b7d9a49711d40d4dc892e7f6bfc1af --- docs/README.md | 11 --- docs/source/API_action_commands.rst | 138 ++++++++++++++++++++++++++-- 2 files changed, 131 insertions(+), 18 deletions(-) diff --git a/docs/README.md b/docs/README.md index 59b9a3e2..1b4b1e33 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,23 +32,12 @@ The goal for Shipyard is to provide a customizable *framework* for operators and developers alike. This framework will enable end-users to orchestrate and deploy a fully functional container-based Cloud. - -### Roadmap - -The detailed Roadmap can be viewed on the -[LCOO JIRA](https://openstack-lcoo.atlassian.net/projects/SHIPYARD/issues/) - -- Integrate with DeckHand, DryDock/Promenade, Armada -- Expand funcitionality to provide visibility into and options for operation of - a UCP installation - ### Getting Started This project is under development at the moment. We encourage anyone who is interested in Shipyard to review our [documentation](http://shipyard.readthedocs.io/en/latest/) - ### Bugs If you find a bug, please feel free to create a diff --git a/docs/source/API_action_commands.rst b/docs/source/API_action_commands.rst index 203b811a..f8616791 100644 --- a/docs/source/API_action_commands.rst +++ b/docs/source/API_action_commands.rst @@ -28,7 +28,7 @@ deploy_site ~~~~~~~~~~~ Triggers the initial deployment of a site, using the latest committed -configuration documents. Steps: +configuration documents. Steps, conceptually: #. Concurrency check Prevents concurrent site modifications by conflicting @@ -47,17 +47,17 @@ configuration documents. Steps: #. Armada build Orchestrates Armada to configure software on the nodes as designed. +update_site +~~~~~~~~~~~ + +Applies a new committed configuration to the environment. The steps of +update_site mirror those of deploy_site. Actions under development ~~~~~~~~~~~~~~~~~~~~~~~~~ These actions are under active development -- update_site - - Triggers the initial deployment of a site, using the latest committed - configuration documents. Steps: (a superset of deploy_site) - - redeploy_server Using parameters to indicate which server(s), triggers a redeployment of @@ -68,7 +68,7 @@ Future actions These actions are anticipated for development -- test region +- test region Invoke site validation testing - perhaps baseline is a invocation of all components regular “component” tests. This test would be used as a @@ -80,3 +80,127 @@ These actions are anticipated for development used to interrogate a particular platform component to ensure it is in a working state, and that its own downstream dependencies are also operational + +Configuration Documents +----------------------- +Shipyard requires some configuration documents to be loaded into the +environment for the deploy_site and update_site as well as other workflows +that directly deal with site deployments. + +Schemas +~~~~~~~ +DeploymentConfiguration_ schema - Provides for validation of the +deployment-configuration documents + +Documents +~~~~~~~~~ +deployment-configuration - Allows for specification of configurable options +used by the site deployment related workflows, including the timeouts used for +various steps, and the name of the armada manifest that will be used during the +deployment/update. + +A `sample deployment-configuration`_ shows a completely specified example. + +`Default configuration values`_ are provided for most values. + +Supported values: +''''''''''''''''' + +- physical_provisioner: + + Values in the physical_provisioner section apply to the interactions with + Drydock in the various steps taken to deploy or update bare-metal servers + and networking. + + - deployment_strategy: + + Not currently used, placeholder for specifying how server deployments + should be grouped. (e.g. all-at-once, by-rack, by-label) + + - deploy_interval: + + The seconds delayed between checks for progress of the step that performs + deployment of servers. + + - deploy_timeout: + + The maximum seconds allowed for the step that performs deployment of all + servers. + + - destroy_interval: + + The seconds delayed between checks for progress of destroying hardware + nodes. + + - destroy_timeout: + + The maximum seconds allowed for destroying hardware nodes. + + - join_wait: + + The number of seconds allowed for a node to join the Kubernetes cluster. + + - prepare_node_interval: + + The seconds delayed between checks for progress of preparing nodes. + + - prepare_node_timeout: + + The maximum seconds allowed for preparing nodes. + + - prepare_site_interval: + + The seconds delayed between checks for progress of preparing the site. + + - prepare_site_timeout: + + The maximum seconds allowed for preparing the site. + + - verify_interval: + + The seconds delayed between checks for progress of verification. + + - verify_timeout: + + The maximum seconds allowed for verification by Drydock. + +- kubernetes_provisioner: + + Values in the kubernetes_provisioner section apply to interactions with + Promenade in the various steps of redeploying servers. + + - drain_timeout: + + The maximum seconds allowed for draining a node. + + - drain_grace_period: + + The seconds provided to Promenade as a grace period for pods to cease. + + - clear_labels_timeout: + + The maximum seconds provided to Promenade to clear labels on a node. + + - remove_etcd_timeout: + + The maximum seconds provided to Promenade to allow for removing etcd from + a node. + + - etcd_ready_timeout: + + The maximum seconds allowed for etcd to reach a healthy state after + a node is removed. + +- armada: + + The armada section provides configuration for the workflow interactions with + Armada. + + - manifest: + + The name of the Armada manifest document that the workflow will use during + site deployment activities. e.g.:'full-site' + +.. _DeploymentConfiguration: https://github.com/att-comdev/shipyard/blob/master/shipyard_airflow/schemas/deploymentConfiguration.yaml +.. _`sample deployment-configuration`: https://github.com/att-comdev/shipyard/blob/master/tests/unit/yaml_samples/deploymentConfiguration_full_valid.yaml +.. _`Default configuration values`: https://github.com/att-comdev/shipyard/blob/a88a5cf15a81de32707fee49d7a626908a8c8f38/shipyard_airflow/plugins/deployment_configuration_operator.py#L47