Improve documentation based on feedback from the AWS DevOps competency review
As part of our efforts to complete the process for the AWS DevOps competency we've received feedback from the technical review step.
It's attached here: Technical_Validation_-_GitLab.pdf
The baseline requirements are noted here: Baseline-Requirements-for-Deploy-Guides.pdf
The feedback as a whole is to update our documentation to make it easier for users to deploy GitLab on AWS.
Validation points
-
An introduction that describes the GtLab's intended use as well as a typical deployment on AWS -
An architecture diagram application on AWS -
All technical prerequisites and requirements -
Instructions for creating IAM EC2 instance role and profile -
Information on the cost of using AWS service(s) -
Prescriptive guidance for backup and recovery -
Step-by-step instructions for deploying the workload on AWS -
Instructions for the backup and recovery of the application in case of Availability Zone or region failure -
How to perform any required periodic maintenance, including secure storage -
Step-by-step instructions for actions to take in the event of fault conditions, such as a transient failure of an AWS Service (e.g. availability of EC2 in a particular AZ is degraded), or a more permanent failure of an AWS service (e.g. EC2 instance has faulted, EC2 Scheduled Maintenance Event received) -
Links to materials referenced outside of the document, including AWS-hosted documentation on resources and services used in a deployment.
Missing
-
AWS HA - No prescriptive guidance on how to deploy GitLab to maximize uptime and availability through autoscaling groups, multi-AZ deployment, etc. -
Update diagram - Diagram for the Add Storage section does not reflect the instructions. It states to edit the root volume to 20G but the picture shows 8GB. -
Add how to monitor the AMI - The user guide does not include instructions for monitoring the AMI. -
Steps in case of AWS failure - The user guide does not provide instructions for transient or permanent failure of an AWS service. -
Clearer backup info - When going through the backup directions, the Creating a backup of the GitLab system section, there are directions for installing from the Omnibus package, from source, and running in a Docker container. It is unclear what option someone running the AMI should choose. -
LFS on S3 - For storage, there is no language on or links to the ability to store LFS in S3. -
Link to the HA docs or incorporate the info from there - I noticed that these some points were explicitly left out as they mostly refer to high availability. Why would this be the case? All baseline requirements must be in place in order to close the technical validation for Advanced Tier status. -
Rephrase paragraph on security - In the section for security groups, the recommended language would be something like the following: "Tip: Based on best practices, you should only allow SSH traffic from only a known host or CIDR block. In that case, change the SSH source to be custom and give it the IP you want to SSH from. -
Check if domain is necessary - In the Setting up a domain name section, is this a requirement? It's not clear why a user would want to do this and what it gives them. Would they have to do this if they chose to use an ALB? -
Gitaly - Setup Gitaly
After merge
-
Redirect https://about.gitlab.com/aws to the new guide
Edited by Achilleas Pipinellis