From c28e2e0500c79026bcde8115d27eeec43c71346f Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Sep 23 2019 13:47:10 +0000 Subject: Initial commit/structure for the Fedora Infra public docs Signed-off-by: Pierre-Yves Chibon --- diff --git a/antora.yml b/antora.yml new file mode 100644 index 0000000..81eb931 --- /dev/null +++ b/antora.yml @@ -0,0 +1,16 @@ +# Name will be mostly visible in the URL. Treat it as an indentifier. +# Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page) +name: infra # <---- PLEASE MODIFY + +# Title will be visible on the page. +title: Fedora Infrastructure # <---- PLEASE MODIFY + +# If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version. +version: master + +# We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise. +start_page: ROOT:index + +# This lists all the menu definitions of your component. +nav: +- modules/ROOT/nav.adoc diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..1e4db2d --- /dev/null +++ b/build.sh @@ -0,0 +1,46 @@ +#!/bin/sh + +image="docker.io/antora/antora" +cmd="--html-url-extension-style=indexify site.yml" + +if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "" + echo "This build script is using Docker container runtime to run the build in an isolated environment." + echo "" + docker run --rm -it -v $(pwd):/antora $image $cmd + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # Check whether podman is available, else faill back to docker + # which requires root. + + if [ -f /usr/bin/podman ]; then + echo "" + echo "This build script is using Podman to run the build in an isolated environment." + echo "" + podman run --rm -it -v $(pwd):/antora:z $image $cmd + + elif [ -f /usr/bin/docker ]; then + echo "" + echo "This build script is using Docker to run the build in an isolated environment." + echo "" + + if groups | grep -wq "docker"; then + docker run --rm -it -v $(pwd):/antora:z $image $cmd + else + echo "" + echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password." + echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/." + echo "" + sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd + fi + else + echo "" + echo "Error: Container runtime haven't been found on your system. Fix it by:" + echo "$ sudo dnf install podman" + exit 1 + fi +fi diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc new file mode 100644 index 0000000..5fb6196 --- /dev/null +++ b/modules/ROOT/nav.adoc @@ -0,0 +1,6 @@ +* xref:overview.adoc[A global overview] +* xref:join.adoc[Join the team] +* xref:services.adoc[List of our services] +** xref:sle.adoc[SLE] +*** xref:sle_services.adoc[SLE of the services] +** xref:packaging_overview.adoc[Packaging overview] diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..7a0681a --- /dev/null +++ b/modules/ROOT/pages/index.adoc @@ -0,0 +1,62 @@ +:experimental: += The Fedora Infrastructure + +The Fedora infrastructure is the team of dedicated volunteers and +professionals maintaining the servers and some of the services used to build +Fedora as well as enable its community. + +We're located all over the globe and communicate primarily by IRC and e-mail. + +== Officers + +The team has officers for a number of areas, please consult with them on +matters under their area: + +* Infrastructure Lead - Kevin Fenzi +* Security Officer - Patrick Uiterwijk +* Development Manager - Pierre-Yves Chibon +* Quality Engineering - Tim Flink + +The officers generally decide what needs to be done in the day to day operations +of the various Fedora infrastructure facilities. The officers themselves work +for the developers and end users but ultimately report to the Fedora Project +Council. This basically means that we'll try to do whatever we can to fill needs +and fix things but if we refuse for whatever reason, the final decision can be +made by the Fedora Project Council. Such decisions, however, are rare. + +For more information on our officers and governance method see our Officers +page. + +== Communicating + +The Infrastructure Team coordinates their activities using a variety of tools. +Our primary methods of communication are weekly IRC meetings, the IRC channel +#fedora-admin[?] located on freenode.net, and the mailing list. + +Application development efforts take place in the #fedora-apps[?] IRC channel, +and system administration related efforts take place in the #fedora-noc IRC channel. + +=== Meetings + +We also hold weekly meetings in #fedora-meeting[?] each Thursday at 14:00 UTC. +See the UTC Howto for instructions to convert UTC to your local time. + +See the meetings page for details and historical archives. + +=== IRC + +You can find core members and contributors in the #fedora-admin[?] channel. + +Additionally, for things specific to application development and testing we +have the #fedora-apps[?] channel, and for things related to alerts/outages +and general sysadmin tasks the #fedora-noc[?] channel. + +New to IRC? Have a read of our Beginner's Guide to IRC Beginner's Guide To IRC -- Fedora Magazine + +=== Mailing list + +The mailing list of the Fedora Infrastructure Project is: +https://lists.fedoraproject.org/admin/lists/infrastructure@lists.fedoraproject.org/ + +The archives are available at: +https://lists.fedoraproject.org/archives/list/infrastructure@lists.fedoraproject.org/ diff --git a/modules/ROOT/pages/join.adoc b/modules/ROOT/pages/join.adoc new file mode 100644 index 0000000..37d7050 --- /dev/null +++ b/modules/ROOT/pages/join.adoc @@ -0,0 +1,12 @@ += Join the Fedora Infrastructure + +Fedora is known for creating and using new technologies. The Infrastructure +team helps build many of these new technologies and uses many of them on a +regular basis. We are always interested in discussing these technologies +from an academic and theoretical perspective. + +If you're ready to work with the Fedora Infrastructure team we're looking +for smart, dedicated system administrators and developers to help maintain +our systems and write code. The Fedora Infrastructure team is a perfect way +to give back to the community! So what are you waiting for? Take a look at +our Getting Started Page! diff --git a/modules/ROOT/pages/overview.adoc b/modules/ROOT/pages/overview.adoc new file mode 100644 index 0000000..460df9a --- /dev/null +++ b/modules/ROOT/pages/overview.adoc @@ -0,0 +1,7 @@ += Overview of the Fedora Infrastructure + +== Architecture + +== Tooling + +== Good Practices diff --git a/modules/ROOT/pages/packaging_overview.adoc b/modules/ROOT/pages/packaging_overview.adoc new file mode 100644 index 0000000..cced5f8 --- /dev/null +++ b/modules/ROOT/pages/packaging_overview.adoc @@ -0,0 +1,4 @@ += Packaging overview + +Here is a diagram showing the different applications and services involved in +packaging software for Fedora. diff --git a/modules/ROOT/pages/services.adoc b/modules/ROOT/pages/services.adoc new file mode 100644 index 0000000..704ea64 --- /dev/null +++ b/modules/ROOT/pages/services.adoc @@ -0,0 +1,5 @@ += Fedora services + +This document describes the services ran by the Fedora Infrastructure (note that +they may be maintained by other people or team). + diff --git a/modules/ROOT/pages/sle.adoc b/modules/ROOT/pages/sle.adoc new file mode 100644 index 0000000..7813abe --- /dev/null +++ b/modules/ROOT/pages/sle.adoc @@ -0,0 +1,160 @@ +:experimental: +:toc: += Service Level Expectations + +The infrastructure team does not have any formal agreement or contract regarding +the availability of its different services. However, we do try our best to keep +services running, and as a result, you can have some expectations as to what +we will do to this extent. + +== Primary Business Hours + +Fedora Infrastructure is a community team, involving volunteers as well as +people employed by Red Hat to work on Fedora. +However, despite the help of volunteers primary business hours are mostly +aligned with the workk schedule of Red Hat. Normal hours should be seen as +during Mondayy through Friday 1400 UTC to 2300 UTC with US national holidays and +a 2 weeks end of year closure affecting staffing and response times. + +Services outside of primary business hours are done on call and depend on +the availability of staff. + +== Roles and Responsibilities + +=== Fedora Infrastructure to Community + +* To have staff present and available in appropriate IRC channels to answer + questions during primary hours. +* To have particular staff on-call during off hours so that community + members can contact for Critical and Important services. +* Interact with community members with respect and courtesy. +* Work with community members to get accurate and thorough documentation of + incidents, problems, or feature requests. +* Resolve reported problems as soon as acknowledged if possible. +* Clearly communicate estimated resolution times. +* Move items which can not be resolved within a reasonable time to future + feature requests or close out. + +=== Community Members to Fedora Infrastructure + +* Provide full and detailed reports of the problem or requested service. +* Provide clear and complete contact information and times when available. +* Leave alternative contacts who can also be available in case of vacation + or other emergencies. +* When contacted by Fedora IT, respond back within 5 business days. + +=== Fedora Infrastructure to Fedora Infrastructure + +* Have a clear schedule of reachable hours. +* Set and take regular vacation time to be rested. +* Rotate through days on-call in IRC and tickets. +* If adding a new service, be available outside of normal business hours to + help debug problems. +* Follow procedures and checklists when adding or updating services. +* Help with regular audits of the documentation + +== Definition of Service Priorities + +The general design of service priorities is that of concentric circles, where +items rely on services in their own circle or a circle below them. +//TODO: could use an image + +. *Critical* services are ones which Fedora Infrastructure will work on 24x7 + with a 52 week coverage if an unplanned outage occurs. Services will be + configured to be highly available with an estimated planned/unplanned + uptime of 95%. Response time should be within 1 hour. +. *Important* services are ones which Fedora Infrastructure will work to be + available 24x7 with a 50 week coverage. Response times during primary hours + should be 1 hour, and outside of it should be 4 hours. +. *Normal* services are ones which Fedora Infrastructure will work to be + available during primary work hours. Problems outside of these hours will + be looked at as people are available. The services may be available + outside of these but are of a lower priority than important services. +. *Low priority* services are ones which are not critical or important for + the primary function of Fedora Infrastructure. They will be worked on and + looked at during primary business hours. Response times should be within + 1 business day. +. *Third Party* services are ones which Fedora Infrastructure has outsourced + tools and services to. Uptimes, service hours, and coverage are dictated + by the third party. Depending on the type of problem, Fedora Infrastructure + will act as an intermediary, or in the case of tools like retrace and COPR, + direct the user to talk with the service owners. +. *Deprecated* services are ones which Fedora Infrastructure are no longer + putting resources into. This may be because the project has completed its + mission, the upstream software is dead, or the original reasons for the + product are available. Problems with these services will be looked at + during primary business hours. Responses may be mostly "Will Not Fix". + +== Limitations on Support + +* Some services that are associated with Fedora are provided by third + parties. Changes and outages which affect them are outside the control + of Fedora Infrastructure. +* Fedora Infrastructure will prioritize issues and requests that affect + multiple people or teams over a smaller group or individual. +* Fedora Infrastructure has limited budget and hours. Requests and features + will be prioritized to fit within those. +* Fedora Infrastructure is bound by the laws and regulations of the United + States of America. This means that certain requests, changes and problems + are outside the ability of members to deal with. + +== Glossary + +* **Planned outage**: A planned outage is one that is announced sufficiently + ahead of time to allow most users to plan around it. + +* **Unplanned outage**: An outage that occurs suddenly without proper + allowance for users to plan around it. + +* **Scheduled outage**: An outage which has been scheduled to occur, but may + not have been announced with enough time for users to plan around it. + +* **High Availability**: Systems are available during specified operating + hours with any unplanned outages 'masked' by other tools. + +* **Continuous Operations**: Systems are available 24 hours a day, 7 days + a week, with no scheduled outages. Unplanned outages are possible during + this time. + +* **Continuous Availability**: Systems or applications are available 24x7 + with no planned or unplanned outages. This is a combination of high + availability and continuous operations. + +* **Level of availability**: + +[options=header] +|=== +|Percentage | Max outage time per day +| 90% | 144.0 minutes +| 95% | 72.0 minutes +| 99% | 14.4 minutes +| 99.9% | 1.4 minutes +|=== + +* **Committed Hours of Availability**: Hours that an organization will have + staff available to help deal with issues with systems, services, and + applications. Also known as "Regular Business Hours" + +* **Outage Hours**: Total number of hours of outage considered normal for + calculating achieved availability. + +* **Response Time**: The time between the users notification of the problem + and when the help desk will begin to work on that problem. + +* **Resolution Update**: The frequency of updates to tickets + +== Estimated Time of Resolution: +//TODO: this is missing the actual times +By priority Levels: + +* **Emergency**: Problems which are site wide, and affect the core functions + of the project. + +* **Urgent**: Problems which affect multiple functions and groups in the + project. + +* **Normal**: Problems which affect a single user from performing needed + duties. + +* **Low**: A request for service, instruction, information that has no + immediate impact on services. diff --git a/modules/ROOT/pages/sle_services.adoc b/modules/ROOT/pages/sle_services.adoc new file mode 100644 index 0000000..17e2d74 --- /dev/null +++ b/modules/ROOT/pages/sle_services.adoc @@ -0,0 +1,151 @@ +:experimental: +:toc: += Services SLE + +Here is the list of our services per SLE level. For memory these levels are +presented in our xref:sle.adoc[SLE Documentation]. + +[WARNING] +==== +This document is still a **work in progress**. The services listed +there are at their appropriate level for Fedora but not all of them are under +the responsabilities of the CPE team which is currently not represented here. +==== + +== Critical + +* DNS +* Bastion ssh +* Authentication/authorization (FAS) https://admin.fedoraproject.org/accounts/ +* Authentication/authorization (Ipsilon) https://id.fedoraproject.org +* Configuration Management (ansible) +* Source control (git) +* Backups +* DHCP/PXE +* IPA + + +== Important + +* Koji https://koji.fedoraproject.org +* Bodhi https://bodhi.fedoraproject.org +* Downloads https://dl.fedoraproject.org/ +* Fedora Souce code https://src.fedoraproject.org/ +* MirrorManager https://admin.fedoraproject.org/mirrormanager +* Nagios https://nagios.fedoraproject.org +* HAProxy https://admin.fedoraproject.org/haproxy/proxy01 +* Postgres databases +* Mysql databases +* Product Definition Center https://pdc.fedoraproject.org/ +* Greenwave +* Fedmsg +* DataGrepper https://apps.fedoraproject.org/datagrepper/ +* Email gateway bastion.fedoraproject.org +* Autosign +* Composer +* Buildhosts +* Docker registry +* Memcached +* Logging +* Basset +* PDC +* resultsdb +* certgetter +* mbs +* odcs + + +== Normal + +* Pagure https://pagure.io +* CI https://ci.centos.org +* The Mailing Lists https://lists.fedoraproject.org +* Wiki https://fedoraproject.org/wiki/Fedora_Project_Wiki +* Documentation +* Notifications https://apps.fedoraproject.org/notifications +* Kerneltest https://apps.fedoraproject.org/kerneltest +* Fedora InfraCloud https://fedorainfracloud.org +* FMN +* FAF +* Beaker +* Freshmaker +* Data Analysis + + +== Low + +* Ambassadors https://fedoraproject.org/membership-map/ambassadors.html +* Asknot http://whatcanidoforfedora.org/ +* Badges https://badges.fedoraproject.org/ +* Blocker Bugs https://qa.fedoraproject.org/blockerbugs/ +* Easyfix https://fedoraproject.org/easyfix/ +* Elections https://apps.fedoraproject.org/#Elections +* FedoCal https://apps.fedoraproject.org/#FedoCal +* Fedora Magazine https://fedoramagazine.org/ +* Fedora People https://fedorapeople.org/ +* GeoIP https://geoip.fedoraproject.org/ +* github2fedmsg https://apps.fedoraproject.org/github2fedmsg +* Mdapi https://apps.fedoraproject.org/mdapi/ +* Meetbot https://apps.fedoraproject.org/#Meetbot +* Nuancier https://apps.fedoraproject.org/#Nuancier +* Paste https://paste.fedoraproject.org +* Release Monitoring (anitya) https://release-monitoring.org/ +* Review Status https://fedoraproject.org/PackageReviewStatus/ +* The Planet https://fedoraplanet.org/ +* Unbound +* Autocloud +* Bugyou +* Gobby +* Keys +* Koschei +* Loopabull +* Hotness +* OpenShift +* statscache +* Packages https://admin.fedoraproject.org/pkgdb/packages/ +* bugzilla2fedmsg +* fed-image +* zanata2fedmsg +* secondary +* freemedia +* pager_server +* bz_review +* websites + + +== Websites + +* fedora-web +* fedora-budget +* fedora-docs +* developer +* whatcanidoforfedora +* membership-map +* zanata +* review-stats +* fedora_owner_change + +== Third Party + +Outside of Fedora Infrastructure to fix. + +* Network connectivity to PHX2/RDU2 +* FreeNode IRC https://freenode.net +* Ask Fedora https://ask.fedoraproject.org/ +* COPR https://copr.fedorainfracloud.org/ +* Retrace https://retrace.fedoraproject.org +* Bugzilla https://bugzilla.redhat.com/ +* Status https://status.fedoraproject.org +* Taskotron https://taskotron.fedoraproject.org/ +* Openqa +* Taiga https://teams.fedoraproject.org/ + +== Deprecated + +* Torrents https://torrent.fedoraproject.org +* Darkserver https://darkserver.fedoraproject.org/ +* PkgDB https://admin.fedoraproject.org/pkgdb/ +* Jenkins https://jenkins.fedorainfracloud.org/ +* summershum +* Tagger https://apps.fedoraproject.org/tagger/ +* Taiga https://taiga.fedorainfracloud.org/ diff --git a/preview.sh b/preview.sh new file mode 100755 index 0000000..acc52af --- /dev/null +++ b/preview.sh @@ -0,0 +1,18 @@ +#!/bin/sh + +if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "The preview will be available at http://localhost:8080/" + docker run --rm -v $(pwd):/antora:ro -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro -p 8080:80 nginx + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # Fedora Workstation has python3 installed as a default, so using that + echo "" + echo "The preview is available at http://localhost:8080" + echo "" + cd ./public + python3 -m http.server 8080 +fi diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..9c23d8d --- /dev/null +++ b/site.yml @@ -0,0 +1,20 @@ +site: + title: Local Preview + start_page: infra:ROOT:index +content: + sources: + - url: . + branches: HEAD +ui: + bundle: + url: https://asamalik.fedorapeople.org/ui-bundle.zip + snapshot: true + default_layout: with_menu +output: + clean: true + dir: ./public + destinations: + - provider: archive +runtime: + pull: true + cache_dir: ./cache