Docs: AWS install - corrections + troubleshooting suggestions
What does this MR do?
This MR suggests improvements to the AWS installation documentation based on my own experience of setting up a self-managed GitLab instance following it.
Corrections - Load Balancer section
- The documentation currently suggests the reader sets up a Listener ruler to forward HTTPS traffic from port 443 on the load balancer to port 443 on the instance - but later on the guide (under 'Add support for proxied SSL') the GitLab instance is configured to listen on port 80 only, with SSL traffic terminated at the load balancer. The rule should be forwarding port 443 on the load balancer to port 80 on the instance.
- The documentation instructs the reader not to add any instances to the load balancer when creating it, but to come back after creating your GitLab instances and add them - but the auto scaling group is set up to manage this automatically. The user should not come back and manually add instances to the load balancer at any point.
Suggestions - Troubleshooting
The Troubleshooting section is added to include a couple of potential pain points:
- The user is only asked to set a
root
password once the Auto Scaling group is established, but the GitLab instance(s) will fail health checks until a password is set, because the sign-in endpoint used as a health check will return a status302
code (in redirecting the user to the password set screen) instead of the200
response needed. - This is less specific to AWS, but I also experienced a 422/CRSF token authenticity issue which turned out to be a mismatch between
external_url
ingitlab.rb
and the domain I was accessing the instance on. Because this installation involves instances behind a load balancer with its own DNS, in turn behind some other domain, and users might also assign a public IP to an instance to debug during install (especially if the LB health checks are failing), this might crop up again and save yet another 422/CRSF token post on the forum.
I realise that this introduces the troubleshooting section where there is currently none. If there is a desire to avoid introducing it, I can update the MR to work in the reference to health checks failing on redirects, which is likely to be a common problem given the installation sequencing in the guide.
Does this MR meet the acceptance criteria?
Conformity
N/A
Availability and Testing
N/A
Security
N/A