Getting Started
Prerequesite
To install the Kubefirst Platform see nebulous install
After Nebulous Install
The kubefirst/nebulous
execution includes a lot of important information toward the end including URLs and passwords. Do not lose this information.
Nebulous provisions some cloud resources, including a self-hosted GitLab Server and an EKS cluster with the following content installed in it:
Application | Description |
---|---|
Nginx Ingress Controller | Ingress Controller |
Cert Manager | Certificate Automation Utility |
Certificate Issuers | Let's Encrypt browser-trusted certificates |
Argo CD | GitOps Continuous Delivery |
Argo Workflows | Application Continuous Integration |
GitLab Runner | GitLab CI Executor |
Vault | Secrets Management |
Atlantis | Terraform Workflow Automation |
External Secrets | Syncs Kubernetes secrets with Vault secrets |
Chart Museum | Helm Chart Registry |
Metaphor Development | Development instance of sample application |
Metaphor Staging | Staging instance of sample application |
Metaphor Production | Production instance of sample application |
- These apps are all managed by Argo CD and the app configurations are in the
gitops
repo'sregistry
folder - The AWS infrastructure is terraform - that's also in your
gitops
repo, but in yourterraform
Step 1: Connect to GitLab, Kubernetes, and Vault
The nebulous output provides you with connection details to your GitLab, Kubernetes, and Vault applications.
Please make sure you can connect to all three before continuing.
Step 2: Save the connection details provided by nebulous
Look for this line in your nebulous output:
...
#############################################################################################
#
# !!!! !!! !!! !!! KEEP EVERYTHING PRINTED FROM THIS LINE DOWN !!!! !!! !!! !!!
#
#############################################################################################"
Copy everything from there to the end and store it in a safe place. The nebulous output will include sensitive values, please protect accordingly.
Step 3: The Atlantis Workflow for Terraform
Navigate to the gitops
project in your GitLab server, and then to Merge Request. Open the Merge Request titled test the atlantis workflow
.
This particular pull request touches files within each of the 5 terraform entry points:
- terraform/argocd
- terraform/base
- terraform/gitlab
- terraform/users
- terraform/vault
The souce of truth for these entry points can be found in atlantis.yml
in the gitops
root directory.
Submit a comment on that Merge Request with the following comment text:
atlantis apply
Doing so will invoke Atlantis to apply the plan. It will report back with the results of the apply within a minute or two.
NOTE: Atlantis merges your Pull Request automatically once an apply is successfully executed. Don't merge Atlantis merge requests yourself.
Atlantis will always run plans automatically for you when a merge request is opened that changes files mapped in atlantis.yaml
Step 4: Deliver Metaphor to Production
Metaphor is our sample application that we use to demonstrate parts of the platform and to test CI changes. It's the other project in the Kubefirst group in GitLab.
If you visit its .gitlab-ci.yml
in the repo root, you'll see it's sending some workflows to argo. Those workflows are also in the metaphor
repo in the .argo
directory.
The metaphor pipeline will:
- publish the metaphor container to your private ecr
- add the metaphor image to a release candidate helm chart and publish it to chartmuseum
- set the metaphor desired helm chart version in the gitops repo for development, then staging
- the release stage of the pipeline will republish the chart, this time without the release candidate notation making it an officially released version, and prepare the metaphor application chart for the next release version
- the officially released chart will be set as the desired helm chart for production
To watch this pipeline occur, make any change to the main
branch of the metaphor
repo. If you're not feeling creative, we put a file at .argo/ci-files/trigger.txt
that you can use. Once a file in main
is changed, navigate to metaphor's CI/CD in GitLab to see the workflows get submitted to argo workflows.
You can visit the metaphor development, staging, and production apps in your browser to see the versions change as your releases complete and argocd syncs the apps. The metaphor URLs can be found in your gitops and metaphor project README.md
files.
Step 5: Set up your team in SSO
GitLab serves as our OIDC provider for the developer and admin user groups. The users in these groups are granted access to Vault, Argo CD, Argo Workflows, and GitLab itself. It's all managed with terraform. There are some sample users in the gitops repo at:
- gitops/terraform/users/admins.tf
- gitops/terraform/users/developers.tf
You'll find some sample users named admin1, admin2, developer1, and developer2 in these files. This is just for you to explore how it works before changing these files to your actual team.
Add your team's admins and developers in a branch. Merge request the change so Atlantis can generate the plan.
Review the plan, and atlantis apply
once everything looks right.
The new users will all have temporary credentials stored in vault in the users
secret store. Distribute those passwords to your engineers.
With these SSO credentials, admins and developers will have reasonable starting points throughout the kubefirst platform.
Learning the ropes
We've tried our best to surface available customizations and patterns of the kubefirst platform here on our docs site. We've also made links available to all of our open source tools' own sources of documentation as well.
You can reach out to us if you have any issues along the way. We're also available for consultation of where you should take the platform based on your organization's needs. We know the stack inside and out and would love to help you do the same.