Kylie Norquist: GitLab Installation and Administration Basics
module-name: "GitLab Installation and Administration Basics"
area: "Product Knowledge"
gitlab-group: "Enablement:Distribution"
maintainers:
- TBD
Introduction
Welcome to the next step in your onboarding pathway!
As you work through this onboarding issue, remember that this issue is non-confidential and is public. Please do not add confidential data such as customer names, logs, etc. to this issue. Linking to the appropriate Zendesk ticket is OK!
Goals of this checklist
At the end of the checklist, new team member should
- Be comfortable with the different installation options of GitLab.
- Have an installation available for reproducing customer bug reports.
- Get your development machine set up.
General Timeline and Expectations*
- Read about our Support Onboarding process; the page also shows you the different modules you'll need to complete as part of your Onboarding.
- This issue should take you one week to complete.
Installation and Administration
As a Support Engineer you will keep one personal installation of GitLab continually updated on Google Cloud Platform (managed through Terraform), just like many of our clients. This installation will serve as your goto spot to quickly reproduce customer bug reports. Additionally, you should make yourself familiar with other ways to install GitLab. Note: When setting up older versions of GitLab, it's important to keep in mind that they may pose a risk due to unpatched security vulnerabilities. If you're testing an older version of GitLab and the instance is internet facing, it is strongly recommended to apply IP filtering and vulnerability mitigations to minimize the risk of exploitation.
-
Create a new test instance after reading up on the different kinds of test environments. - If you have any issues or questions, ask in the
#support_testing
channel.
- If you have any issues or questions, ask in the
-
Read up about our different Installation Methods -
Set up your test environments; make sure to set up at least: -
GCP (for example using Sandbox Cloud using Terraform) -
Docker or a local VM - Note: If you're using a Mac with M1 / Apple Silicon, running GitLab with Docker might not work yet. In this case, try using a local VM via UTM as an alternative that's confirmed to work.
-
Feel free check out alternative environments like AWS, Azure or different approaches for local VMs like UTM, VMWare, Vagrant, etc.
-
-
-
Install GitLab in the test environments you set up above: -
Install via Omnibus on GCP -
Populate with some test data: User account, Project, Issue -
Backup using our Backup rake task
-
-
Install via Docker or a local VM on your local machine. -
Restore the backup you just created to this installation using our Restore rake task
-
-
Install a GitLab Runner and connect it to your GitLab instance.
-
-
Add Elastic Search to your test environments: -
Install on a VM or a separate instance on Terraform - The steps outlined in our support resources documentation should help you configure your instance's IP.
- Set
cluster.name
andnode.name
and use the latter incluster.initial_master_nodes
to enable "single node" mode.
-
Connect Elastic Search to your GitLab instance and index your repositories. You need to apply a license to your GitLab instance for the integration settings to appear if you haven't already.
-
-
Read up about the support workflow for Generating GitLab Team Member Licenses -
Use the GitLab Team Member License request template to request for licenses for Self-Managed Starter, Premium and Ultimate tiers. Ensure that you create a separate issue for each type of license. Refer to the January 2021 announcement blog post for more information on changes to the Self-Managed Starter tier. -
Store your licenses securely in 1Password. Use the licenses on your test instance when replicating customer issues. By having the correct license, you will ensure feature parity with what the customer is seeing.
-
-
Watch the 2022 GitLab Debugging Techniques: A Support Engineering Perspective video on GitLab Unfiltered (YouTube). This dives into some common issues that customers might experience. -
Keep this installation up-to-date as patch and version releases become available, just like our customers would. If your test instance is publicly available, keep it secured and disable user Sign-ups. You can check this box, but please keep this installation up-to-date as long as you are a Support Engineer for GitLab. -
As stated in the handbook, cloud resources are not free. Please stop your instances you aren't using.
(Optional) Setting up some services to use with GitLab
The services below are part of the many services used by our customers. Installing these services and learning how they work with GitLab will give you a solid foundation for when you're ready to resolve tickets on your own. Complete as many of these now as you are interested in, but be sure to familiarize yourself with all of them in the future. Consider pairing with your onboarding buddy to learn from any challenges which may arise!
-
Connect your GitLab instance to a cluster via the Kubernetes clusters integration and install a Runner in the cluster: -
Log in to https://gitlabsandbox.cloud/ and sign in with your Okta account to get access to the GitLab Sandbox Cloud. If you haven't created your account yet, this is a good opportunity to do so by following these steps. -
Once you have created an account, you can proceed and create a cluster under your own GCP project. Start small to cut costs to about one tenth of the default cluster config: - Set Location type
to a single zone (instead of a region) - SetNode pool
Size
to 1 - Set theNodes
'Machine type
to asmaller
one than the default (recommende2-medium
for 2vCPU and 4GB RAM) - Review the general tips for cost optimization -
Find your cluster and click connect
next to your cluster. Then click onRun in Cloud Shell
. -
Add the Kubernetes cluster to GitLab. Use the Cloud Shell to run the kubectl
commands as needed. ** Needs updating **- Be aware that when copying data from the Cloud Shell, it might add extra characters to soft wrapped strings.
-
Create a project on your self-managed instance and then create a file named .gitlab-ci.yml
. -
Use the YAML docs as a resource to build a basic script. -
Make sure your project has access to your Kubernetes cluster under Operations -> Kubernetes. -
Make sure your project has registered runners under your project's Settings -> CI/CD -> Runners. -
Pat yourself on the back; you're now ready to reproduce some of our common customer tickets. -
Remove the cluster when you're done!
-
-
Install GitLab from Source. Installation from source is not common but will give you a greater understanding of the components that we employ and how everything fits together. - Have a copy of GitLab source code available offline for reference -
In the future, you may need other applications for testing. Don't set these up now, but check out the infrastructure for troubleshooting section of workflows, so you know what's available.
(Optional) Setting up GDK
-
You can install the GDK, which is what you'd need later on in case you want to contribute code changes to GitLab. - If you like Docker, especially if you're running Linux on your desktop, consider the GitLab Compose Kit as an alternative.
Congratulations! You made it, and now have an understanding of the different ways in which GitLab can be installed and managed.
You are now ready to continue on your onboarding path to tackle the next module in line. Reach out to your manager or onboarding buddy if it is not assigned to you yet; you can check the training page or your New Support Team Member Start Here
issue to see the list of all modules under your Onboarding pathway!
If you think of any improvements to this module, please submit an MR! The file is located in an issue template in the 'support-training` repository.