Skip to content

Docs: AWS install - corrections + troubleshooting suggestions

Ciaran Morinan requested to merge CiaranMn/gitlab:docs/update-aws-install-guide into master

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 status 302 code (in redirecting the user to the password set screen) instead of the 200 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 in gitlab.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

Merge request reports