diff --git a/README.md b/README.md index 967ab38..67232cb 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,209 @@ -# Ministry of Justice Template Repository +# NVVS DevOps Containers Repository [![repo standards badge](https://img.shields.io/endpoint?labelColor=231f20&color=005ea5&style=for-the-badge&label=MoJ%20Compliant&url=https%3A%2F%2Foperations-engineering-reports.cloud-platform.service.justice.gov.uk%2Fapi%2Fv1%2Fcompliant_public_repositories%2Fendpoint%2Ftemplate-repository&logo=data:image/png;base64,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)](https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/public-report/template-repository) -This template repository equips you with the default initial files required for a Ministry of Justice GitHub repository. +## Docker container for local terraform development -## Included Files +Here the NVVS DevOps development container is defined. -The repository comes with the following preset files: +It can be used locally to enable a consistent development experience across platforms +(Linux, Windows, MacOS (Intel & M1 ARM)). -- LICENSE -- .gitignore -- CODEOWNERS -- dependabot.yml -- GitHub Actions example file -- Ministry of Justice Compliance Badge (Public repositories only) +### How to build -## Setup Instructions +Prerequisite Docker installed, Make. -Once you've created your repository using this template, ensure the following steps: +```shell +make build +``` -### Update README +### How to use -Edit this README.md file to document your project accurately. Take the time to create a clear, engaging, and informative README.md file. Include information like what your project does, how to install and run it, how to contribute, and any other pertinent details. +Suggestion for use with [AWS-VAULT](https://ministryofjustice.github.io/nvvs-devops/documentation/team-guide/best-practices/use-aws-sso.html#configure-aws-vault) -### Update repository description +#### Freeflow -After you've created your repository, GitHub provides a brief description field that appears on the top of your repository's main page. This is a summary that gives visitors quick insight into the project. Using this field to provide a succinct overview of your repository is highly recommended. +Create an alias for use with the local build -This description and your README.md will be one of the first things people see when they visit your repository. It's a good place to make a strong, concise first impression. Remember, this is often visible in search results on GitHub and search engines, so it's also an opportunity to help people discover your project. +```shell +alias toold='docker run --rm -ti -v $(pwd):/data --env-file <(aws-vault exec $AWS_PROFILE -- env | grep ^AWS_) ministryofjustice/nvvs/terraforms:latest' +``` -### Grant Team Permissions +In terraform directory run -Assign permissions to the appropriate Ministry of Justice teams. Ensure at least one team is granted Admin permissions. Whenever possible, assign permissions to teams rather than individual users. +```shell +toold +``` -### Read about the GitHub repository standards +To use the version hosted on the [GitHub Container Registry](https://github.blog/tag/container-registry/) attached to this repository/ -Familiarise yourself with the Ministry of Justice GitHub Repository Standards. These standards ensure consistency, maintainability, and best practices across all our repositories. +```shell +alias tooldgh='docker run --rm -ti -v $(pwd):/data --env-file <(aws-vault exec $AWS_PROFILE -- env | grep ^AWS_) ghcr.io/ministryofjustice/nvvs/terraforms:v0.2.0' +``` -You can find the standards [here](https://operations-engineering.service.justice.gov.uk/documentation/services/repository-standards.html). +### Tools included -Please read and understand these standards thoroughly and enable them when you feel comfortable. +See the [Dockerfile](./Dockerfile) for full details. However initially this container is a large utility container to reduce developer friction while upgrading the repositories to a consistent version(s) of Terraform. -### Modify the GitHub Standards Badge +- Terraform (via TFENV) +- AWS CLI v2 +- TFLINT +- kubectl +- helm -Once you've ensured that all the [GitHub Repository Standards](https://operations-engineering.service.justice.gov.uk/documentation/services/repository-standards.html) have been applied to your repository, it's time to update the Ministry of Justice (MoJ) Compliance Badge located in the README file. +### Create tagged release -The badge demonstrates that your repository is compliant with MoJ's standards. Please follow these [instructions](https://operations-engineering.service.justice.gov.uk/documentation/runbooks/services/add-repo-badge.html) to modify the badge URL to reflect the status of your repository correctly. +NOTE: This needs refining. -**Please note** the badge will not function correctly if your repository is internal or private. In this case, you may remove the badge from your README. +- Push the branch to github and get a pull request approved. +- Merge to main +- Depending on the increment run `make tag SEMVAR=[ patch | minor | major ]` -### Manage Outside Collaborators +## Example usage in Makefile -To add an Outside Collaborator to the repository, follow the guidelines detailed [here](https://github.com/ministryofjustice/github-collaborators). +This is an example of how it can be used with one of the NVVS DevOps Terraform projects. -### Update CODEOWNERS +```makefile +#!make +.DEFAULT_GOAL := help +SHELL := '/bin/bash' -(Optional) Modify the CODEOWNERS file to specify the teams or users authorized to approve pull requests. +CURRENT_TIME := `date "+%Y.%m.%d-%H.%M.%S"` +TERRAFORM_VERSION := `cat versions.tf 2> /dev/null | grep required_version | cut -d "\\"" -f 2 | cut -d " " -f 2` -### Configure Dependabot +LOCAL_IMAGE := ministryofjustice/nvvs/terraforms:latest +DOCKER_IMAGE := ghcr.io/ministryofjustice/nvvs/terraforms:v0.2.0 -Adapt the dependabot.yml file to match your project's [dependency manager](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem) and to enable [automated pull requests for package updates](https://docs.github.com/en/code-security/supply-chain-security). +DOCKER_RUN := @docker run --rm \ + --env-file <(aws-vault exec $$AWS_PROFILE -- env | grep ^AWS_) \ + --env-file <(env | grep ^TF_VAR_) \ + --env-file <(env | grep ^ENV) \ + -e TFENV_TERRAFORM_VERSION=$(TERRAFORM_VERSION) \ + -v `pwd`:/data \ + --workdir /data \ + --platform linux/amd64 \ + $(DOCKER_IMAGE) -If your repository is private with no GitHub Advanced Security license, remove the .github/workflows/dependency-review.yml file. +DOCKER_RUN_IT := @docker run --rm -it \ + --env-file <(aws-vault exec $$AWS_PROFILE -- env | grep ^AWS_) \ + --env-file <(env | grep ^TF_VAR_) \ + --env-file <(env | grep ^ENV) \ + -e TFENV_TERRAFORM_VERSION=$(TERRAFORM_VERSION) \ + -v `pwd`:/data \ + --workdir /data \ + --platform linux/amd64 \ + $(DOCKER_IMAGE) + +export DOCKER_DEFAULT_PLATFORM=linux/amd64 + +.PHONY: aws +aws: ## provide aws cli command as an arg e.g. (make aws AWSCLI_ARGUMENT="s3 ls") + $(DOCKER_RUN) /bin/bash -c "aws $$AWSCLI_ARGUMENT" + +.PHONY: shell +shell: ## Run Docker container with interactive terminal + $(DOCKER_RUN_IT) /bin/bash + +.PHONY: fmt +fmt: ## terraform fmt + $(DOCKER_RUN) terraform fmt --recursive + +.PHONY: init +init: ## terraform init (make init ENV_ARGUMENT=pre-production) NOTE: Will also select the env's workspace. + +## INFO: Do not indent the conditional below, make stops with an error. +ifneq ("$(wildcard .env)","") +$(info Using config file ".env") +include .env +init: -init +else +$(info Config file ".env" does not exist.) +init: -init-gen-env +endif + +.PHONY: -init-gen-env +-init-gen-env: + $(MAKE) gen-env + $(MAKE) -init + +.PHONY: -init +-init: + $(DOCKER_RUN) terraform init --backend-config="key=terraform.$$ENV.state" + $(MAKE) workspace-select + +.PHONY: init-upgrade +init-upgrade: ## terraform init -upgrade + $(DOCKER_RUN) terraform init -upgrade --backend-config="key=terraform.$$ENV.state" + +.PHONY: import +import: ## terraform import e.g. (make import IMPORT_ARGUMENT=module.foo.bar some_resource) + $(DOCKER_RUN) terraform import $$IMPORT_ARGUMENT + +.PHONY: workspace-list +workspace-list: ## terraform workspace list + $(DOCKER_RUN) terraform workspace list + +.PHONY: workspace-select +workspace-select: ## terraform workspace select + $(DOCKER_RUN) terraform workspace select $$ENV || \ + $(DOCKER_RUN) terraform workspace new $$ENV + +.PHONY: validate +validate: ## terraform validate + $(DOCKER_RUN) terraform validate + +.PHONY: plan-out +plan-out: ## terraform plan - output to timestamped file + $(DOCKER_RUN) terraform plan -no-color > $$ENV.$(CURRENT_TIME).tfplan + +.PHONY: plan +plan: ## terraform plan + $(DOCKER_RUN) terraform plan + +.PHONY: refresh +refresh: ## terraform refresh + $(DOCKER_RUN) terraform refresh + +.PHONY: output +output: ## terraform output (make output OUTPUT_ARGUMENT='--raw dns_dhcp_vpc_id') + $(DOCKER_RUN) terraform output -no-color $$OUTPUT_ARGUMENT + +.PHONY: apply +apply: ## terraform apply + $(DOCKER_RUN) terraform apply + $(DOCKER_RUN) /bin/bash -c "./scripts/publish_terraform_outputs.sh" + +.PHONY: state-list +state-list: ## terraform state list + $(DOCKER_RUN) terraform state list + +.PHONY: show +show: ## terraform show + $(DOCKER_RUN) terraform show -no-color + +.PHONY: destroy +destroy: ## terraform destroy + $(DOCKER_RUN) terraform destroy + +.PHONY: lock +lock: ## terraform providers lock (reset hashes after upgrades prior to commit) + rm .terraform.lock.hcl + $(DOCKER_RUN) terraform providers lock -platform=windows_amd64 -platform=darwin_amd64 -platform=linux_amd64 + +.PHONY: clean +clean: ## clean terraform cached providers etc + rm -rf .terraform/ terraform.tfstate* .env + +.PHONY: gen-env +gen-env: ## generate a ".env" file with the correct TF_VARS for the environment e.g. (make gen-env ENV_ARGUMENT=pre-production) + $(DOCKER_RUN) /bin/bash -c "./scripts/generate-env-file.sh $$ENV_ARGUMENT" + +.PHONY: tfenv +tfenv: ## tfenv pin - terraform version from versions.tf + tfenv use $(cat versions.tf 2> /dev/null | grep required_version | cut -d "\"" -f 2 | cut -d " " -f 2) && tfenv pin + +help: + @grep -h -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' + + +```