'Tutorial: Set up workspaces infrastructure on AWS'

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:

Fork the repository
Set up AWS credentials
Prepare domain and certificates
Create required keys
Create a GitLab Agent for Kubernetes token
Configure GitLab OAuth
Configure CI/CD variables
Update GitLab agent configuration
Run the pipeline
Configure DNS records
Authorize the agent
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.

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:

Go to the Workspaces Infrastructure Setup AWS repository.
Create a fork of the repository. For more information, see Create a fork.

Set up AWS credentials

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

To set up AWS credentials:

Create an IAM User or IAM Role.

Assign the following permissions:

{
  "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": "*"
    }
  ]
}

Create an access key for the user or role.
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:

Buy a domain or use an existing domain for your workspaces environment.
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:

Generate a signing key consisting of random letters, numbers, and special characters. For example, run:
```
openssl rand -base64 32
```
Generate an SSH host key:
```
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:

Go to your group.
On the left sidebar, select Search or go to and find your project.
Select Operate > Kubernetes clusters.
Select Connect a cluster.
Enter a name for your agent and save for later use. For example, gitlab-workspaces-agentk-eks.
Select Create and register.
Save the token and KAS address for later use.
Select Continue.

Configure GitLab OAuth

Next, set up OAuth authentication to securely access workspaces.

To configure GitLab OAuth:

Go to User settings:
1. Select your profile picture, then select Preferences.
On the left sidebar, select Applications.
Scroll down to OAuth applications.
Select Add new application.
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.
Select Save application.
Save the Application ID and Secret for your CI/CD variables.
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:

On the left sidebar, select Search or go to and find your project.
Select Settings > CI/CD.
Expand Variables.

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 token for Kubernetes.
`TF_VAR_kas_address`	GitLab Kubernetes Agent Server 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.

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 GitLab agent configuration

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

To update the GitLab agent configuration:

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

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.

Update the file with the following required fields:

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

For more configuration options, see Workspace settings.

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:

Create a new pipeline in your GitLab project:
1. On the left sidebar, select Build > Pipelines.
2. Select New pipeline and select New pipeline again to confirm.
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:

Get the Ingress-NGINX load balancer address from the pipeline output:
```
kubectl get services -n ingress-nginx ingress-nginx-controller
```
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 to connect to your GitLab instance.

To authorize the agent:

On the left sidebar, select Search or go to and find your group.
Select Settings > Workspaces.
In the Group agents section, select the All agents tab.
From the list of available agents, find the agent with status Blocked, and select Allow.
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:

Create a new workspace by following the steps in Create a workspace.
From your project, select Edit.
Select your workspace name.
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.