The GitLab Demo Systems provide infrastructure for the GitLab Customer Success, Marketing, Sales, and Training teams to demonstrate GitLab features, value propositions, and workflows in a variety of asynchronous and live capacities.
The Demo Systems were architected by Jeff Martin starting in October 2019 when he was a Senior Demo Systems Engineer. We have other team members that contributed to help support our users and infrastructure (James Sandlin and Cristiano Casella). We also collaborate with counterparts in other departments for broader GitLab infrastructure configuration in AWS, GCP, etc and security incident response.
In June 2021, Jeff Martin changed roles to a Senior IT Systems Engineer and the Demo Systems program became a managed service of the IT Engineering Infrastructure team. We continue to maintain the infrastructure and Kubernetes support in the #demo-systems
Slack channel and related channels listed below.
For questions about what demo sample projects are available or peer assistance with troubleshooting your failed pipeline job, please ask in the #cs-questions
Slack channel.
Please tag @Jeff Martin
in one of the following Slack channels with any questions or requests related to infrastructure or access requests.
#demo-systems
is for SA, CSM, and PSE team members with questions or needing technical assistance. No longer for training/workshop related posts.#demo-systems-workshops
is for workshop-related discussions.#demo-systems-ps-education
is for ILT/SPT/etc related discussions for Professional Services.#sandbox-cloud-questions
is for help and support with the Sandbox CloudPlease consider this handbook documentation to be the single source of truth ("SSOT") for all resources that use the gitlabdemo.com
, gitlabdemo.cloud
, and gitlabtraining.cloud
domain names.
Why shouldn’t we just use GitLab.com? Although you can use GitLab.com for showing most of the value of GitLab use cases, there are some administrative features that require the deployment of GitLab Omnibus infrastructure in AWS, GCP, or local VM/container. Many of our enterprise customers opt for self-managed over GitLab.com so we are mindful of “showing the customer what they’ll see in production”.
What’s special about our infrastructure? The demo systems infrastructure doesn’t do anything special that a customer or partner company couldn’t do themselves with the appropriate staffing and engineering investment. We have open sourced our infrastructure-as-code methods, scripts and tools for the wider community to use to streamline their deployment of Omnibus infrastructure. See the gitlab-com/demo-systems repositories to explore our open source projects.
Are there special engineering or scalability considerations with training classes and workshops? Yes. The GitLab product was designed for users to be doing different activities throughout the day and the smaller reference architectures are not designed for dozens or hundreds of users to click the same button and running the same background jobs or pipeline jobs at the same time. Our users are also ephemeral and have automated garbage collection requirements that are not customary for conventional GitLab product use cases. This requires special scalability considerations, notably with the Container Registry, Sidekiq, and Kubernetes that we have to accommodate for. Here's some of the things we're looking for with scalability challenges.
.gitlab-ci.yml
without realizing the underlying job load..gitlab-ci.yml
files without comments of the actions being performedThese shared environments are referred to as the Demo Cloud or Training Cloud. Historically, training users used the Demo Cloud so the names are used interchangably in some conversations.
gitlab-core.us.gitlabdemo.cloud
instance was deprecated on 2021-04-20 and destroyed on 2021-06-03. No data back up is available. See Access Shared Omnibus Instances instructions for accessing the cs.gitlabdemo.cloud
instance (direct replacement).cs.gitlabdemo.cloud
- This is the primary GitLab Omnibus instance that all team members have access to for creating groups, projects, and sandbox purposes on a self-managed Omnibus instance. Please keep in mind that this is a shared environment across all team members and you should treat the Admin areas as read-only.ilt.gitlabtraining.cloud
- This is used for instructor-led training classes. You should generate credentials for this instance if you are an instructor and need admin access to be able to import sample projects and/or see the groups for all of the students in a class.spt.gitlabtraining.cloud
- This is used for self-paced training classes that are published in EdCast. You should only generate credentials for this instance if you are involved with instructional design or certification grading of self-paced student courses. If you are enrolled in a self-paced training class, you should follow the instructions for redeeming an invitation code to generate temporary credentials that can be used for accessing the instance that has been pre-configured for the training lab guide steps.workshop.gitlabtraining.cloud
- This is used for enablement and field marketing workshops that are delivered on a routine basis. You should generate credentials for this instance if you are involved creating lab sample projects, lab guides, presenting, or supporting a workshop.group-cs
GCP project. See the tutorial for configuring GitLab with group-level Kubernetes cluster to add your cluster to your GitLab group.These instructions are for Demo Systems v2 that uses the gitlabdemo.cloud Portal. The Demo Systems v1 infrastructure that used gitlabdemo.com has been deprecated except for training class invitation codes.
These instructions provide you access to one or more of our shared environments (Omnibus self-managed instances).
The Demo Cloud Portal and provisioning system is powered by gitlabdemo-cloud-app, an open source project created by Jeff Martin.
#cs-questions
Slack channel.See the Sandbox Realm handbook page for instructions on creating your own AWS account and/or GCP project that you can use for deploying your own infrastructure with the benefit of centralized billing.
These instructions are for training class organizers, instructors, and workshop presenters to generate an invitation code that students can redeem to generate credentials for accessing the respective Training Cloud Omnibus instance.
Warning for GitLab team members: This process generates new credentials that are used for accessing the GitLab Demo Portal and/or GitLab Omnibus instance that you may already be authenticated to using your administrative user account.
https://*.gitlabtraining.cloud
).iu######
).Training Users
group.
You will receive a 404 error if you click on the name of the
Training Users
folder since you do not have access to resources in that specific folder. Behind the scenes, this is actually a 403 (Unauthorized) error.
Session ########
group.My Test Group - iu######
group.The workshop process has iterated multiple times. The latest version of the workshop preparation process has been simplified into a self-service model.
As the workshop presenter and supporting team member, you are responsible for importing and testing your sample projects and lab guide content. There is no support provided for misconfigured projects, failing pipelines and jobs, or GitLab Runner error messages specific to projects and jobs.
There is no more peer review or approval process other than scheduling coordination with the field marketing team. You no longer need to create an issue in the Demo Systems Issue Tracker. These instructions provide best practice guidance. If you need assistance, please ask in the #cs-questions
Slack channel to get help from other team members that have delivered similar workshops.
Schedule a Date - This is usually handled by the field marketing team or workshop organizer. As of 2021-04-23, we have a capacity restriction of one workshop per calendar week. The real-time SSOT schedule can be found in field-marketing#3074.
Invitation Code - Create your invitation code using the instructions. This will automatically create the GitLab group (/training-users/session-########
) that all student groups and projects will be created underneath. There is a single invitation code per workshop (specific date) that is shared across all student attendees and any instructors performing the lab steps for testing purposes. We can administratively update the expiration date if your workshop is rescheduled. This invitation code should be added in the field marketing issue.
Import Sample Project(s) - Access the https://workshop.gitlabtraining.cloud Omnibus instance using the administrative credentials that you generated previously and saved in 1Password. Import the project into the Sample Project Templates group and set the project visibility to Public
. This will now appear as an instance level project template when you create a new project as a student.
Redeem the Invitation Code (for test user account) - Open a new browser window in incognito mode and visit https://gitlabdemo.com/invite. Copy and paste the invitation code that you created and click the Redeem and Create Account button. Follow the instructions for invitation code redemption to access the GitLab group that was created for your student user account.
Follow Your Lab Guide Steps - You are now signed in as a student and should run through the steps that you plan on having students run through. It is important to be very detail click-by-click oriented and not use any of your tribal knowledge that your students don't have. All pipelines should pass and have no failed jobs, unless the job failure is specifically documented in your lab guide instructions and the project README. If you run into problems, you will need to debug them and update the lab guide with the fix or solution. There is no support provided for misconfigured projects, failing pipelines and jobs, or GitLab Runner error messages specific to projects and jobs, so it is best practice to do your due diligence and have peers run through the lab guide as well to catch any errors to provide the most polished experience for students. If you need assistance, please ask in the #cs-questions
Slack channel to get help from other team members that have delivered similar workshops.
Day of the Workshop - Use the slides to show students how to properly redeem an invitation code. This can be copied into your lab guide steps. The workshop presenter(s) are responsible for providing support and triaging any problems or failed pipeline job error messages that students see when using your sample project.
Extension Policy - We do not extend workshop access since it is very resource intensive to keep resources around. Students have access to the Training Cloud until 00:00 UTC two days following the workshop (4:00pm PT on the day after the workshop). Ask students to perform an export of any projects that they want to keep that can be reimported into GitLab.com or another Omnibus instance in their own environment. The sample project templates group is publicly accessible for reference at a later time, however iterative changes are to be expected.
All of the workshop content that are created officially can be found in the gitlab-com/customer-success/workshops group. There have historically been many deviations and custom workshops that have been created, so use your best judgement on which sample project to use for your workshop. It is a best practice to test your sample project before every workshop to debug any errors before you have 200 students with problems.
Lab Guide Name | Links | Maintainer |
---|---|---|
Advanced CI/CD | Slides and Sample Projects | @lmwilliams |
Program and Project Management | Slides and Sample Projects | @lmwilliams |
DevOps Automation | Slides and Sample Projects | @lmwilliams |
Security | Slides and Sample Projects | @lmwilliams |
When creating new lab guides for a workshop, you should start planning and creating your workshop labs 6-8+ weeks before the planned date of the workshop. It is a best practice to create and publish your content before scheduling a date for your workshop. As part of our efficiency value, we encourage you to reuse workshop materials from previous events.
These are recommendations (not requirements) to help you be successful based on past experience. You can do what you need to do, however keep in mind that you're responsible for supporting and triaging up to 200 users simultaneously who have problems with the sample projects and lab guides that you create.
[4-6+ weeks prior]
Create or import sample project(s) - Create your code sample project or import your existing sample project into the Sample Project Templates GitLab group and set the visibility to Public
. You can start using your sample project and perform testing using the workshop preparation instructions.[4-6+ weeks prior]
Create a slide deck using the template and add steps for your exercises - This slide deck has the standardized instructions for students to redeem an invitation code and import their project. You will need to add additional slides with the lab exercises being performed in your workshop.
README
.[3-5+ weeks prior]
Publish the link to your sample project in the event issue - After your project is ready for performing lab exercises, update the event issue description with the link to your sample project.[3-5+ weeks prior]
Publish the link to your slides in the issue - After you have added your lab exercise steps, update the event issue description with the link to your slides. The peer review process is up to your discretion.[3-5+ weeks prior]
Record a video of yourself performing lab steps (dry run) - Use your preferred screenshare recording tool (Zoom, Camtasia, Screenflow, etc) to record a video of walking through the lab steps and providing a narrative of what you're doing. This serves as a dry run that other team members can review and serves as a guideline for peer reviewers to follow if your lab steps are not sufficient. You will find that you will explain a lot of things verbally that are not written down and this is a chance to capture it while benefiting the others that are reviewing the labs.[2-4+ weeks prior]
Peer review of lab exercises - The peer reviewers should review the slide deck for understandability and topic coverage. They will also perform the lab exercises as if they are a student to ensure that instructions are easy to understand and follow, and identify any technical issues or possible confusion areas that should be known for the team members assisting with the workshop in real time.
[2-3+ weeks prior]
Final edits and publishing - It is expected that there will be several hours of edits to make to the slides or lab exercises based on the peer review.[1-3+ weeks after]
Publish to catalog - After the workshop has been completed and any reported problems are mitigated, you should publish the lab guide for your workshop to the catalog for future re-use.We perform version upgrades on the weekend following the 22nd of each month. The weekend upgrades are performed at a random time on Saturday or Sunday based on engineer availablility and lasts for approximately 30 minutes.
We delay the upgrade window for updates that we consider risky or occur during holidays. This occurs during May each year that aligns with the US Memorial Day holiday, in December around the Christmas Holiday, and in January at the end of the fiscal year when we have a configuration freeze until sales demos are completed.
For patch and security updates, we will usually only perform upgrades for critical updates and will announce maintenance windows in the #demo-systems
channel on Slack.
The cs.gitlabdemo.cloud
instance is upgraded to the latest version on the second or third weekend after release (minimum 10 days) to allow time for patch versions. The ilt
, spt
, and workshop
training instances are version locked based on training content and are upgraded in conunction with course material updates.
GitLab Version | Release Date | Upgrade Window (Sat to Sun) |
---|---|---|
v14.3 | 2021-09-22 (Wed) | 10-02 to 10-03 |
v14.4 | 2021-10-22 (Fri) | 11-06 to 11-07 |
v14.5 | 2021-11-22 (Mon) | 12-03 to 12-04 |
v14.6 | 2021-12-22 (Wed) | 2022-01-01 to 01-02 |
v14.7 | 2022-01-22 (Sat) | 02-05 to 02-06 |
v14.8 | 2022-02-22 (Tue) | 03-05 to 03-06 |
v14.9 | 2022-03-22 (Tue) | 04-02 to 04-03 |
v14.10 | 2022-04-22 (Fri) | 05-07 to 05-08 |
We keep our shared environment up-to-date with the latest versions to help showcase the value that the newest features and solutions offer.
For demo and sandbox use cases requiring an older version, you can deploy a GitLab instance in a container in the Container Sandbox or using Omnibus in the Compute Sandbox. We do not offer any data migration or parity configuration support.
Historically, there has not been a consistent set of demo data. Each of our Solutions Architects are responsible for creating their own demo data or forking projects from other team members.
See the handbook page for Demo Readiness and Existing Demonstrations to get started.
Please see the Solutions Architecture Initiatives issue tracker for more information on the crowd sourced OKRs that are in progress and the development of our Communities of Practice.
These are the projects that make the Demo Systems possible behind the scenes. You are welcome to study and learn from any of our source code. Each project is classified as Public
or Private
depenending on the security risk of the source code or information contained within.
The Demo Systems v2 repositories can be found in gitlab.com/gitlab-com/demo-systems.
Public
Underlying Terraform Modules and Ansible Role
Public
Assembled Terraform Modules and Environments
Private
Environments IaC - see terraform/terraform.tfvars.json
and CI pipeline
Public
Management Applications
Private - Ops
Sandbox Cloud Infrastructure
Private
Runbooks
The Demo Systems v1 repositories can be found in gitlab.com/gitlab-com/customer-success/demo-systems.
Private
Terraform Monolith Environments and Modules
Private
Ansible Monolith Configuration and Roles
Private
Management Applications (gitlabdemo.com)
We use Slack for real-time support and quick fixes. If in doubt of how to get help, ask in #demo-systems
. The issue trackers are used for tasks and projects that take longer than 30 minutes. We do not use email for internal team communications.
#demo-systems
Slack channel (for Demo Cloud announcements, questions, and technical support with Demo Cloud)#demo-systems-ps-education
Slack channel (for ILT/SPT training lab discussions)#demo-systems-workshops
Slack channel (for workshop discussions)#sandbox-cloud
Slack channel (for Sandbox Cloud announcements)#sandbox-cloud-questions
Slack channel (for Sandbox Cloud questions and technical support)demo-systems-admin@gitlab.com
(for non-Slack users)