From 642c6c2d883ece68134867f69c7c2853b8ba5c2e Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Thu, 3 Sep 2020 10:54:35 +1000 Subject: [PATCH] Update README.rst Update this to be more relevant to 2020 Change-Id: I6389fe292baf2f56d8b9dc6bb876e4ec4ed5e984 --- README.rst | 98 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 82 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 21a61ab643..c9bfbf3708 100644 --- a/README.rst +++ b/README.rst @@ -1,26 +1,92 @@ -Puppet Modules -============== +OpenDev System Configuration +============================ -These are a set of puppet manifests and modules that are currently being -used to manage the OpenStack Project infrastructure. +This is the machinery that drives the configuration, testing, +continuous integration and deployment of services provided by the +OpenDev project. -The main entry point is in manifests/site.pp. +Services are driven by Ansible playbooks and associated roles stored +here. If you are interested in the configuration of a particular +service, starting at ``playbooks/service-.yaml`` will show you +how it is configured. -In general, most of the modules here are designed to be able to be run -either in agent or apply mode. +Most services are deployed via containers; many of them are built or +customised in this repository; see ``docker/``. -These puppet modules require puppet 2.7 or greater. Additionally, the -site.pp manifest assumes the existence of hiera. +A small number of legacy services are still configured with Puppet. +Although the act of running puppet on these hosts is managed by +Ansible, the actual core of their orchestration lives in ``manifests`` +and ``modules``. -See http://docs.openstack.org/infra/system-config for more information. +Testing +------- + +OpenDev infrastructure runs a complete testing and +continuous-integration environment, powered by `Zuul +`__. + +Any changes to playbooks, roles or containers will trigger jobs to +thoroughly test those changes. + +Tests run the orchestration for the modified services on test nodes +assigned to the job. After the testing deployment is configured +(validating the basic environment at least starts running), specific +tests are configured in the ``testinfra`` directory to validate +functionality. + +Continuous Deployment +--------------------- + +Once changes are reviewed and committed, they will be applied +automatically to the production hosts. This is done by Zuul jobs +running in the ``deploy`` pipeline. At any one time, you may see +these jobs running live on the `status page +`__ or you could check +historical runs on the `pipeline results +`__ (note +there is also an ``opendev-prod-hourly`` pipeline, which ensures +things like upstream package updates or certificate renewals are +incorporated in a timely fashion). + + +Contributing +============ + +Contributions are welcome! + +You do not need any special permissions to make contributions, even +those that will affect production services. Your changes will be +automatically tested, reviewed by humans and, once accepted, deployed +automatically. + +Bug fixes or modifications to existing code are great places to start, +and you will see the results of your changes in CI testing. + +You can develop all the playbooks, roles, containers and testing +required for a new service just by uploading a change. Using a +similar service as a template is generally a good place to start. If +deploying to production will require new compute resources (servers, +volumes, etc.) these will have to be deployed by an OpenDev +administrator before your code is committed. Thus if you know you +will need new resources, it is best to coordinate this before review. + +The `#opendev `__ IRC +channel is the main place for interactive discussion. Feel free to +ask any questions and someone will try to help ASAP. The `OpenDev +meeting `__ is a +co-ordinated time to synchronize on infrastructure issues. Issues +should be added to the `agenda +`__ for +discussion; even if you can not attend, you can raise your issue and +check back on the logs later. There is also the `service-discuss +`__ +mailing list where you are welcome to send queries or questions. Documentation ============== -The documentation presented at http://docs.openstack.org/infra/system-config comes from -https://opendev.org/opendev/system-config repo's docs/source. To -build the documentation use +The latest documentation is available at +https://docs.opendev.org/opendev/system-config/latest/ -:: - - tox -evenv python setup.py build_sphinx +That documentation is generated from this repository. You can geneate +it yourself with ``tox -e docs``.