Local code edits¶

By default, the codebase is set up to use stable versions, or specific branch names, of our code and released in GitLab. This is however a cumbersome way to develop, an easier method is to point your solution to local versions of the code instead.

Terraform¶

Note: upstream also has a guide on possible sources for module, which you can use as a reference when needed.

By default, Terraform will fetch the GET module from the Terraform Module Registry in GitLab:

module "gitlab_cluster" {
  source = "git.glhd.nl/glh/gitlab-environment-toolkit/aws"
  version = "3.1.2"
  # ...
}

Alternatively, you can use a Git repository source instead:

module "gitlab_cluster" {
  source = "git::git@git.glhd.nl:glh/ha/gitlab-environment-toolkit.git//terraform/aws?ref=main"
  # ...
}

For local development, things are slightly complicated. Terraform does not allow using absolute paths, so you must point to the source variable as a relative path instead. This example below assumes the following two paths:

/home/user/projects/gitlab-environment-toolkit - Git repository of GET
/home/user/projects/solutions/environment-name - Codebase of the solution

Then the relative path in environment.tf is:

module "gitlab_cluster" {
  source = "../../../gitlab-environment-toolkit/terraform/aws/"
  # ...
}

Ansible¶

Ansible uses shared codebases in multiple ways. The Python dependencies, such as Ansible itself, and the Boto libraries, are managed via a Pip dependency. In most cases you won't need to update this manually. If that is required, you can simply pass the path to the folder where pyproject.toml, or setup.py lives as an argument to pip install.

For the Ansible collections, which are managed by the ansible-galaxy tool, there is no local symlinking feature, so you must create the symlinks yourself. Not doing this means you must re-run ansible-galaxy install after each change.

Becuse we bypass ansible-galaxy, any subdependencies must be manually installed. You can find the subdependencies in the galaxy.yml file in the relevant collection.

First, ensure Ansible will look in an additional folder for local collections by editing ansible.cfg:

[defaults]
; Prepend ./collections to the search path
collections_path = ./collections:.ansible/collections:/opt/ansible/collections

Then, create this folder in a structure that Ansible recognises, and create symlinks to the upstream codebase.

mkdir -p collections/ansible_collections/glh
ln -s ~/projects/gitlab-environment-toolkit/ansible collections/ansible_collections/glh/environment_toolkit

Note the usage of underscores instead of dashes, the path on disk must match the namespace name that is used normally.

Ansible will now look for any GET code directly on your local disk. If you also have a copy of GET in any of the other folders in collections_path, you may run into issues when creating syntax errors or removing files from your local checkout. It's best to remove these duplicates to avoid issues.

If you want to use the ansible-galaxy tool after this, you must call it with an override for the collection path, otherwise your local namespace folder will be polluted with global collections:

COLLECTIONS_PATHS=".ansible/collections" ansible-galaxy install -r galaxy-requirements.yml