Tutorial: Set up workspaces infrastructure on AWS

<!-- vale gitlab_base.FutureTense = NO -->

This tutorial guides you through the GitLab workspaces infrastructure setup on AWS using OpenTofu, an open-source fork of Terraform through Infrastructure as Code (IaC).

Before you begin

To follow this tutorial, you must have:

• An Amazon Web Services (AWS) account.
• A domain name for your workspaces environment.

To set up GitLab workspaces infrastructure:

1. Fork the repository
2. Set up AWS credentials
3. Prepare domain and certificates
4. Create required keys
5. Create a GitLab Agent for Kubernetes token
6. Configure GitLab OAuth
7. Configure CI/CD variables
8. Update the GitLab agent for Kubernetes configuration
9. Run the pipeline
10. Configure DNS records
11. Authorize the agent
12. Create a workspace and verify setup

Fork the repository

First, you need to create your own copy of the infrastructure setup repository so that you can configure it for your environment.

[!note] It is not possible to create workspaces from projects in your personal namespace. Instead, fork the repository to a top-level group or subgroup.

To fork the repository:

1. Go to the Workspaces Infrastructure Setup AWS repository.
2. Create a fork of the repository.

Set up AWS credentials

Next, set up the necessary permissions in AWS so the infrastructure can be properly provisioned.

To set up AWS credentials:

1. Create an IAM User or IAM Role.

2. Assign the following permissions:

   jsonCopy

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "VisualEditor0",
         "Effect": "Allow",
         "Action": [
           "ec2:*",
           "eks:*",
           "elasticloadbalancing:*",
           "autoscaling:*",
           "cloudwatch:*",
           "logs:*",
           "kms:DescribeKey",
           "kms:TagResource",
           "kms:UntagResource",
           "kms:ListResourceTags",
           "kms:CreateKey",
           "kms:CreateAlias",
           "kms:ListAliases",
           "kms:DeleteAlias",
           "iam:AddRoleToInstanceProfile",
           "iam:AttachRolePolicy",
           "iam:CreateInstanceProfile",
           "iam:CreateRole",
           "iam:CreateServiceLinkedRole",
           "iam:GetRole",
           "iam:ListAttachedRolePolicies",
           "iam:ListRolePolicies",
           "iam:ListRoles",
           "iam:PassRole",
           "iam:DetachRolePolicy",
           "iam:ListInstanceProfilesForRole",
           "iam:DeleteRole",
           "iam:CreateOpenIDConnectProvider",
           "iam:CreatePolicy",
           "iam:TagOpenIDConnectProvider",
           "iam:GetPolicy",
           "iam:GetPolicyVersion",
           "iam:GetOpenIDConnectProvider",
           "iam:DeleteOpenIDConnectProvider",
           "iam:ListPolicyVersions",
           "iam:DeletePolicy"
         ],
         "Resource": "*"
       }
     ]
   }
   

3. Create an access key for the user or role.

4. Save your access key ID and secret access key. You'll need them when configuring CI/CD variables later.

Prepare domain and certificates

For your workspaces to be accessible, you'll need a domain and TLS certificates to secure the connections.

To prepare your domain and certificates:

1. Buy a domain or use an existing domain for your workspaces environment.
2. Create TLS certificates for:
   • GitLab Workspaces Proxy Domain. For example, workspaces.example.dev.
   • GitLab Workspaces Proxy Wildcard Domain. For example, *.workspaces.example.dev.

For more information, see generate TLS certificates.

Create required keys

Now you need to create security keys for authentication and SSH connections.

To create the required keys:

1. Generate a signing key consisting of random letters, numbers, and special characters. For example, run:

   shellCopy

   openssl rand -base64 32
   

2. Generate an SSH host key:

   shellCopy

   ssh-keygen -f ssh-host-key -N '' -t rsa
   

Create a GitLab agent for Kubernetes token

The GitLab agent for Kubernetes connects your AWS Kubernetes cluster to GitLab.

To create a token for the agent:

1. Go to your group.
2. In the top bar, select Search or go to and find your project.
3. Select Operate > Kubernetes clusters.
4. Select Connect a cluster.
5. Enter a name for your agent and save for later use. For example, gitlab-workspaces-agentk-eks.
6. Select Create and register.
7. Save the token and GitLab Relay (KAS) address for later use.
8. Select Continue.

Configure GitLab OAuth

Next, set up OAuth authentication to securely access workspaces.

To configure GitLab OAuth:

1. In the upper-right corner, select your avatar.

2. Select Edit profile.

3. In the left sidebar, select Access > Applications.

4. Scroll down to OAuth applications.

5. Select Add new application.

6. Update the following settings:

   • Name: GitLab Workspaces Proxy
   • Redirect URI: For example, https://workspaces.example.dev/auth/callback. Replace with your user-defined domain.
   • Select the Confidential checkbox.
   • Scopes: api, read_user, openid, and profile.

7. Select Save application.

8. Save the Application ID and Secret for your CI/CD variables.

9. Select Continue.

Configure CI/CD variables

Now, you need to add the necessary variables to your CI/CD configuration so the infrastructure pipeline can run.

To configure CI/CD variables:

1. In the top bar, select Search or go to and find your project.

2. Select Settings > CI/CD.

3. Expand Variables.

4. In the Project variables section, add the following required variables:

   Variable	Value
   AWS_ACCESS_KEY_ID	AWS access key ID.
   AWS_SECRET_ACCESS_KEY	AWS secret access key.
   TF_VAR_agent_token	GitLab agent for Kubernetes token.
   TF_VAR_kas_address	GitLab Relay (KAS) address. Required if on a GitLab Self-Managed instance. For example, wss://kas.gitlab.com.
   TF_VAR_workspaces_proxy_auth_client_id	OAuth application client ID.
   TF_VAR_workspaces_proxy_auth_client_secret	OAuth application secret.
   TF_VAR_workspaces_proxy_auth_redirect_uri	OAuth callback URL. For example, https://workspaces.example.dev/auth/callback.
   TF_VAR_workspaces_proxy_auth_signing_key	Your generated signing key.
   TF_VAR_workspaces_proxy_domain	Domain for the workspaces proxy.
   TF_VAR_workspaces_proxy_domain_cert	TLS certificate for the proxy domain.
   TF_VAR_workspaces_proxy_domain_key	TLS key for the proxy domain.
   TF_VAR_workspaces_proxy_ssh_host_key	Your generated SSH host key.
   TF_VAR_workspaces_proxy_wildcard_domain	Wildcard domain for workspaces.
   TF_VAR_workspaces_proxy_wildcard_domain_cert	TLS certificate for the wildcard domain.
   TF_VAR_workspaces_proxy_wildcard_domain_key	TLS key for the wildcard domain.

5. Optional. Add any of these variables to customize your deployment:

   Variable	Value
   TF_VAR_region	AWS region.
   TF_VAR_zones	AWS availability zones.
   TF_VAR_name	Name prefix for resources.
   TF_VAR_cluster_endpoint_public_access	Public access to cluster endpoint.
   TF_VAR_cluster_node_instance_type	EC2 instance type for Kubernetes nodes.
   TF_VAR_cluster_node_count_min	Minimum number of worker nodes.
   TF_VAR_cluster_node_count_max	Maximum number of worker nodes.
   TF_VAR_cluster_node_count	Number of worker nodes.
   TF_VAR_cluster_node_labels	Map of labels to apply on the cluster nodes.
   TF_VAR_agent_namespace	Kubernetes namespace for the agent.
   TF_VAR_workspaces_proxy_namespace	Kubernetes namespace for workspaces proxy.
   TF_VAR_workspaces_proxy_ingress_class_name	Ingress class name.
   TF_VAR_ingress_nginx_namespace	Kubernetes namespace for Ingress-NGINX.

Great job! You've configured all the necessary variables for your infrastructure deployment.

Update the GitLab agent for Kubernetes configuration

Now, you need to configure the GitLab agent for Kubernetes to support workspaces.

To update the agent configuration:

1. In your forked repository, open the .gitlab/agents/gitlab-workspaces-agentk-eks/config.yaml file.

   [!note] The directory that contains the config.yaml file must match the agent name you created in the create a GitLab agent for Kubernetes token step.

2. Update the file with the following required fields:

   yamlCopy

   remote_development:
     enabled: true
     dns_zone: "workspaces.example.dev"  # Replace with your domain
   

   For more configuration options, see workspace settings.

3. Commit and push these changes to your repository.

Run the pipeline

It's time to deploy your infrastructure. You'll run the CI/CD pipeline to create all the necessary resources in AWS.

To run the pipeline:

1. Create a new pipeline in your GitLab project:
   1. In the left sidebar, select Build > Pipelines.
   2. Select New pipeline and select New pipeline again to confirm.
2. Verify the plan job succeeds, then manually trigger the apply job.

When the OpenTofu code runs, it creates these resources in AWS:

• A Virtual Private Cloud (VPC).
• An Elastic Kubernetes Service (EKS) cluster.
• A GitLab agent for Kubernetes Helm release.
• A GitLab Workspaces Proxy Helm release.
• An Ingress NGINX Helm release.

Excellent! Your infrastructure is now being deployed. This might take some time to complete.

Configure DNS records

Now that your infrastructure is deployed, you need to configure DNS records to point to your new environment.

To configure DNS records:

1. Get the Ingress-NGINX load balancer address from the pipeline output:

   shellCopy

   kubectl get services -n ingress-nginx ingress-nginx-controller
   

2. Create DNS records that point your domains to this address. For example:

   • workspaces.example.dev → Load balancer IP address
   • *.workspaces.example.dev → Load balancer IP address

Authorize the agent

Next, you'll authorize the GitLab agent for Kubernetes to connect to your GitLab instance.

To authorize the agent:

1. In the top bar, select Search or go to and find your group.
2. Select Settings > Workspaces.
3. In the Group agents section, select the All agents tab.
4. From the list of available agents, find the agent with status Blocked, and select Allow.
5. On the confirmation dialog, select Allow agent.

Create a workspace and verify setup

Finally, let's make sure everything is working correctly by creating a test workspace.

To verify your workspace setup:

1. Create a new workspace by following the steps in create a workspace.
2. From your project, select Code.
3. Select your workspace name.
4. Interact with the workspace by opening the Web IDE, accessing the terminal, or making changes to project files.

Congratulations! You've successfully set up GitLab workspaces infrastructure on AWS. Your users can now create development workspace environments for their projects.

If you encounter any issues, check the logs for additional details and refer to troubleshooting workspaces for guidance.

Related topics

• Workspaces
• Configure workspaces
• Workspace settings
• Tutorial: Create a custom workspace image that supports arbitrary user IDs