This repository is a tentative approach to offer a set of add-ons that will provide a day-0 platform ready to be used in a matter of hours instead of weeks.
To accomplish that, it uses the ArgoCD app of apps concept.
Therefore, ArgoCD is the main requirement to run this project on your cluster.
PLEASE NOTE: This project is currently WIP and NOT stable. Use at your own risk!
HINT This project uses
tiltto bring up environment, but there are 2 executables namedtilt. If you already have it on your system, make sure that you are using tilt.dev instead of Ruby tilt
If you dont have argocd on your cluster, the following command will install it with required configuration. Make sure that you are using the correct Kubernetes context before run.
$ make argocdIf you already have argocd (if installed with helm, the name of the chart should be argocd) deployed in your cluster to make deployment successful and all addons synced it is required to verify if following configuration is part of your ArgoCD configuration: argocd/values.yaml.
You can check it by describing argo-cd config map:
kubectl describe cm argocd-cm -n argocd
Don't apply changes directly to the Config Map, but apply them the in your installation scripts/helm chart values.
Next, you can download the provided app-of-apps.yaml in our latest stable release and then apply that manifest using this command:
kubectl apply -f app-of-apps.yamlFull list of the addons that the manifest is installing and additional information for each of them can be found in the docs/ADDONS.md file.
You can pass your own values or override default values to the addons by modifying the app-of-apps.yaml manifest, you can get more details here docs/ADDONS.md
Below there is a matrix with the cloud providers & Kubernetes versions our setup has been tested with.
| Cloud Provider | Kubernetes Version |
|---|---|
| AWS | 1.27 |
| GCP | 1.27 |
| Azure | 1.27 |
You need Docker installed (or similar solutions) to run this project.
Here you can find a list of possible candidates:
- Docker ( cross-platform, paid solution )
- Rancher Desktop ( cross-platform, FOSS )
- lima + nerdctl ( macOS only )
Remember that to run this solution you also need at least:
- 4 CPU cores
- 8 GB RAM - Maybe is necessary to increase Docker limits to use more RAM or Swap to run all components with 8GB RAM.
- 16 GB Disk space
Those numbers are not written in stone so your mileage may vary depending on which components you choose to install.
HINT: To run everything on Windows machine is recommended to use WSL and install Docker inside this subsystem.
HINT: If you want to remove the automatically installed dependencies via asdf once you're done with this project, you can run
make asdf_uninstall.
To continue with the deployment, you need a set of tools installed first. You can either install them manually (see .tool-versions ), or you can install them automatically by following these steps:
- Install
asdf-vm - Run the following command:
make asdf_install
HINT: If you want to know which commands are available you can always run
make helpon this project.
Make sure you've followed the bootstrap steps, then:
$ make ciOnce completed, you're ready to interact with the cluster using kubectl as usual.
The current Kubernetes version that will run locally in the project is defined in the .envrc file, using the variable K8S_VERSION. If you want to run a different local k8s version, please change this value.
Github runners are using a matrix strategy to run unit and integration tests on three different k8s versions.
Take a look at the .github/workflows/integration.yaml or .github/workflows/preview.yaml for an example.
Make sure you've followed the bootstrap steps, then:
-
Deploy the local environment:
# Deploy the cluster and run tilt visually $ makeYou can access the Kind K8s cluster using any kubernetes client like kubectl or Lens.
Accessing Argocd UI -
(Optional) Run the two following resources in tilt to portforward argocd and get the default admin password
- argocd-portforward - argocd-passwordPLEASE NOTE: The port forwarding sometimes seems to drop, so re-run the tilt resource to get the connection up and running again.
-
(Optional) Test app-of-apps values changes using the override feature of the bootstrap app, following the instructions in the
./manifests/bootstrap/overrides.local.yaml.tmplfile.
IMPORTANT: Make sure to run this command while tilt is NOT running.
In order to cleanup the solution from your own local environment you can run:
$ make cleanAll the tests are inside the tests folder. This folder contains tests written in golang to check if the charts
configurations are valid. To create the tests, we use terratest.
Terratest provides a variety of helper functions created by Gruntwork,
To make the infrastructure test setup easier.
Before running tests make sure you've followed the bootstrap steps.
Once ready, you can use this simple set of commands:
# Create the cluster
$ INITIUM_DEPLOY_MINIMAL=true make ci
# Run the unit tests
$ make unit-testAs unit tests, we also use terratest. The main difference is that each test is encapsulated by its goal. See the examples/sample-app as an example.
Before running tests make sure you've followed the bootstrap steps.
Once ready, you can use this simple set of commands:
# Create the cluster and all the required dependencies
$ make ci
# Run the unit tests
$ make integration-testIf you desire to contribute to this project, please make sure you have read the CONTRIBUTING.md file first.
Once you feel ready for it, remember to fork this repository.
Clone your fork into your own local workstation, then finally run the following command to install the project dependencies using asdf-vm and precommit hooks:
cd path/to/initium-platform
make bootstrapYou're now ready to contribute!
After deploying the cluster, you may wish to integrate it with a CI tool of choice. For more information on this subject, consult CI Service Account Readme