infrastructure-components

README

infrastructure-components

Welcome

Demo

Getting Started

Contributing

Global Guidelines

• You can find contributing guidelines in CONTRIBUTING.md
• Feeling like something could be improved? Let's do it together! From code to documentation, services to use, or linter rules, everything is discussable and improvable, make a PR! Let's move forward together.

Concepts

• A repository such as this one is representing a project
• A project is basically an application
• An application is a microservice that works with other microservices to to achieve project's goals
• Microservices are small, loosely coupled, and independently deployable and scalable
• Each microservice should be agnostic of it downstreams. However, it should expose a clear and well-defined API to its downstreams for them to consume (that is, the microservice itself uses its upstreams' API)

Documentation

• Go code documentation is accessible thanks to pkgsite! Just run pkgsite in the root of the project to serve its documentation
• Global project documentation is available in the doc directory

Development Guidelines and Conventions

• All major directories contain a PURPOSE.md file with a brief description of directory's content and instructions on how to use it
• You are encouraged to create your own README.md files in subdirectories to provide project-specific instructions, and to document more-widely scoped topics in doc directory
• Code sharing is encouraged, such code should be placed in pkg and internal/pkg directories, as-per Go's conventions
• Importing other applications libraries and packages is encouraged, following code sharing encouragement
• First class code documentation (following Go doc comment guidelines) as well as project documentation is encouraged
• Following Learn Go with tests is encouraged
• Following Effective Go and Google's styleguide is encouraged
• Following locality of behaviour and principle of least astonishment is encouraged
• Checking Go proverbs is encouraged
• Variables, functions, methods, ... should be named in a short and descriptive way

Project development

• Deploy dev stacks of the layers, in ascending order of layer number (XX- prefix)
• Make changes and enjoy hot reloading!
• Once you are happy with your changes, create a PR!

Prerequisites

• Docker & Docker Compose to run applications in containers. You should configure your credentials store and credential helpers for Docker to work with your container registry
• Go to install applications dependencies as needed

Running the project

• Common tasks such as running, testing, creating new IaC components, updating Cloud resources, ... are done by using kemutil. You are encouraged to install and use it!

Debugging

• Debugger support is available in VSCode, using vscode-go extension. A task is available in .vscode/tasks.json to run the debugger. Please note that you first need to run the application through docker compose with debug profile, e.g. via kemutil

CI / CD

Locally

• CI pipelines can be mimicked locally using ci-cd image, mounting project's directory as a volume in /src, and running the same commands as in the CI pipeline

• That is, you can run the following command to run the whole CI pipeline locally:

  kemutil ci [--fix] [--hot] ci
  

• When using --hot, your need to export GIT_TOKEN environment variable to propagate your git credentials to the container, so that it can fetch private dependencies. This is typically done by running:

  export GIT_TOKEN=$(gh auth token)
  

• Other commands are available, feel free to run kemutil help to see the list of available commands and their usage

False positives

• CI Pipelines can sometime report false positives. Here is what you can do to remediate (be as specific as possible on silences to avoid shadowing real issues):
  • golangci-lint: Add a nolint:<linter>[,<linter>] // <explanation> comment. See this doc
  • semgrep: Add a nosemgrep: <rule-id> comment. See this doc
  • gitleaks: Add finding fingerprint to .gitleaksignore. See this doc. Please note that any leaked secret should be revoked and replaced as soon as possible
  • markdownlint: Add a markdownlint-disable <rule> comment. See this doc
  • shellcheck: Add a shellcheck disable=<rule> comment. See this doc
  • hadolint: Add a hadolint ignore=<rule> comment. See this doc
  • actionlint: In case of a shellcheck error, refer to the shellcheck section. Otherwise, you can pass arguments to the linting action to ignore specific rules. See this doc
  • grype: Add an ignore in .grype.yaml. See this doc. Please note that any vulnerability should be remediated as soon as possible, only add real real positives to the ignore list. Prefer deploying with a non-exploitable vulnerability reported rather than ignoring it.