VS Code for SRE and DevOps on macOS

Introduction

VS Code is a free, extensible code editor from Microsoft that runs on macOS. This guide configures it for day-to-day SRE and DevOps work: Kubernetes, Terraform, Docker and GitLab. The extensions and settings below are suggestions, so adapt them to your team.

Prerequisites: install the CLI tools

Several extensions call command-line tools installed on your Mac (Terraform, kubectl, Docker). Install them first. The commands below use Homebrew.

Install the DevOps and SRE tools

Install the CLI tools before you configure VS Code:

$ brew tap hashicorp/tap
$ brew install git kubernetes-cli helm awscli checkov docker hashicorp/tap/terraform

Terraform comes from HashiCorp’s own Homebrew tap. The docker formula is built from the Docker CLI repository, so it provides the command-line client only: to run containers you also need a container engine, for example Docker Desktop (Homebrew cask docker-desktop).

Optional: TFLint (Terraform linter)

TFLint is optional. The TFLint README lists this Homebrew command, as well as a direct download from the GitHub releases:

$ brew install terraform-linters/tap/tflint

Check that the tools work. The versions below are placeholders: yours will differ.

$ terraform --version
Terraform vX.Y.Z
$ kubectl version --client
Client Version: vX.Y.Z
$ helm version
version.BuildInfo{Version:"vX.Y.Z", ...}
$ docker --version
Docker version X.Y.Z, build ...
$ aws --version
aws-cli/X.Y.Z ...

Install VS Code

VS Code is free of charge. Install it with Homebrew or download it from the official site.

Install with Homebrew

$ brew install --cask visual-studio-code

Or download it directly from code.visualstudio.com.

Launch VS Code from the terminal

To open VS Code from any terminal, install the code command in your PATH:

1. Open VS Code
2. Press Cmd + Shift + P to open the Command Palette
3. Type Shell Command: Install 'code' command in PATH
4. Select the result, then open a new terminal window

You can now run:

$ code .
# Open the current folder in VS Code
$ code main.tf
# Open a specific file

Useful extensions for SRE and DevOps

Much of VS Code’s value comes from its extensions. Here is a short list, grouped by task.

Install extensions

Install them from the Extensions view (Cmd + Shift + X) or from the command line:

$ code --install-extension ms-kubernetes-tools.vscode-kubernetes-tools
$ code --install-extension hashicorp.terraform
$ code --install-extension ms-azuretools.vscode-docker
$ code --install-extension GitLab.gitlab-workflow
# List what is installed
$ code --list-extensions

Extensions by category

Kubernetes and containers

Infrastructure as Code

Cloud and AWS

Git and GitLab

Syntax, linting and formatting

Productivity

Security scanning does not need an extension: Checkov (installed above) runs from the integrated terminal, for example checkov --directory . to scan the current directory.

VS Code settings for SRE work

The defaults suit most people. These are the adjustments that matter for infrastructure files.

Open settings.json

Press Cmd + Shift + P and type Preferences: Open User Settings (JSON). Merge the keys below into your existing file instead of replacing it. This file accepts // comments.

{
  // Format on save (the formatter is chosen per language below)
  "editor.formatOnSave": true,

  // Terraform: language IDs used by the HashiCorp Terraform extension
  "[terraform]": {
    "editor.defaultFormatter": "hashicorp.terraform"
  },
  "[terraform-vars]": {
    "editor.defaultFormatter": "hashicorp.terraform"
  },

  // YAML: Kubernetes manifests, Helm values, CI files
  "[yaml]": {
    "editor.defaultFormatter": "redhat.vscode-yaml",
    "editor.tabSize": 2
  },

  // Git
  "git.autofetch": true,

  // Skip Terraform provider caches when searching
  "search.exclude": {
    "**/.terraform": true
  }
}

GitLab integration

The GitLab Workflow extension brings issues, merge requests and pipelines into VS Code.

What the extension offers

• Issues and merge requests, in the GitLab panel
• Pipeline status and job output, and validation of your pipeline configuration
• Security findings and SAST scanning
• Read-only access to a GitLab repository without cloning it

Connect VS Code to GitLab

1. Install the GitLab Workflow extension (GitLab.gitlab-workflow)
2. Press Cmd + Shift + P and run GitLab: Authenticate
3. Choose OAuth or Personal Access Token
4. For a self-managed instance, enter its full URL, including https://
5. With a token, create it in your GitLab personal access token settings with the api scope, then paste it into VS Code

Clone a GitLab repository

$ git clone https://gitlab.com/your-group/your-repo.git
$ code your-repo

Or use the Command Palette:

1. Cmd + Shift + P, then Git: Clone
2. Paste the URL of the GitLab repository
3. Choose the destination folder

Typical workflow: create and merge a merge request

$ git checkout -b feature/fix-kubernetes-yaml

$ git push -u origin feature/fix-kubernetes-yaml

GitLab commands

Press Cmd + Shift + P and type GitLab: to list the commands that your version of the extension provides.

Git configuration and commit conventions

Configure Git so that your commits are clear and easy to trace.

Configure Git on macOS

$ git config --global user.name "Your Name"
$ git config --global user.email "you@example.com"
$ git config --global core.editor "code --wait"

The --wait flag makes the command wait until the files are closed, so Git waits for you to finish the commit message in VS Code.

Commit message template

Create a template file to standardize commit messages. This command overwrites ~/.gitmessage if it already exists.

$ cat > ~/.gitmessage << 'EOF'
# type(scope): subject
#
# type: feat, fix, refactor, perf, docs, style, test, ci, chore
# scope: kubernetes, terraform, docker, ci-cd, infra
# subject: short description (a common limit is 50 characters)
#
# Optional body
EOF
$ git config --global commit.template ~/.gitmessage

Git shows this template when you run git commit without -m. Lines that start with # are removed from the final message. The type(scope): subject format follows a common convention (Conventional Commits). Use whatever format your team has agreed on.

Example commits for SRE work

$ git commit -m "feat(kubernetes): add HPA for API deployment"
$ git commit -m "fix(terraform): correct VPC CIDR block for prod-eu1"
$ git commit -m "docs(infra): update Kubernetes runbook for pod crashes"
$ git commit -m "perf(docker): reduce base image size"

Debugging, testing and validation

Beyond editing, VS Code can debug scripts, call APIs, run validation tasks and work inside containers.

Debug a Python script locally

If you have Python scripts for your infrastructure:

1. Install the Python extension (ms-python.python)
2. Create a .vscode/launch.json file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python Debugger: Current File",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    }
  ]
}

Then press F5 to start debugging.

Test APIs with REST Client

Install REST Client, then create a file named api-test.http. Separate requests with ###. Read tokens from environment variables and never write them in the file.

@projectId = 12345

### List the pipelines of a GitLab project
GET https://gitlab.com/api/v4/projects/{{projectId}}/pipelines
PRIVATE-TOKEN: {{$processEnv GITLAB_TOKEN}}

### Create a workspace in HCP Terraform (use a test organization)
POST https://app.terraform.io/api/v2/organizations/MY_ORG/workspaces
Authorization: Bearer {{$processEnv TF_API_TOKEN}}
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "workspaces",
    "attributes": {
      "name": "my-workspace"
    }
  }
}

Click Send Request above a request to run it. The second request creates a real workspace, so point it at a test organization.

Validate Terraform before you push

Define a build task in .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "terraform validate",
      "type": "shell",
      "command": "terraform validate",
      "group": { "kind": "build", "isDefault": true },
      "problemMatcher": []
    }
  ]
}

1. Run terraform init once in the folder, because terraform validate needs an initialized directory
2. Press Cmd + Shift + B (Run Build Task)
3. Errors appear in the integrated terminal

Develop inside containers (Dev Containers)

With the Dev Containers extension and a container engine such as Docker Desktop:

1. Create a .devcontainer folder at the root of the repository
2. Create a devcontainer.json file in it:

{
  "name": "Terraform Dev",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/terraform:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "hashicorp.terraform",
        "ms-kubernetes-tools.vscode-kubernetes-tools",
        "GitLab.gitlab-workflow"
      ]
    }
  }
}

Then press Cmd + Shift + P and run Dev Containers: Reopen in Container. VS Code reopens the folder inside the container, with Terraform installed by the dev container feature and the listed extensions installed automatically.

Shortcuts and productivity tips

These are the default macOS shortcuts. Check yours in Preferences: Open Keyboard Shortcuts.

Themes and appearance

Themes and fonts are a matter of taste. Pick the ones you find comfortable. To switch, run Preferences: Color Theme.

Example color themes

Icon themes

Icon themes help you tell files apart quickly:

• vscode-icons (vscode-icons-team.vscode-icons): an icon theme
• Material Icon Theme (PKief.material-icon-theme): an icon theme

Font for the integrated terminal

If you followed the iTerm2 guide and use Powerlevel10k, use the same MesloLGS NF font in the VS Code terminal. Otherwise the prompt icons appear as broken characters. Install the font first, then add:

{
  "terminal.integrated.fontFamily": "MesloLGS NF"
}

What you have now

You now have an editor set up for:

• Kubernetes (YAML manifests, clusters)
• Terraform (validation, formatting)
• Docker (images and containers)
• GitLab (merge requests, issues, pipelines)
• AWS
• Python, shell and other languages
• Local debugging and validation tasks

Official documentation

• GitLab Workflow extension for VS Code: overview
• GitLab Workflow extension: install and authenticate
• VS Code on macOS: setup and the code command
• VS Code: command-line extension management
• VS Code: Python debugging
• VS Code: tasks
• VS Code: Dev Containers
• HashiCorp Terraform extension for VS Code (README)

Keep going