Explore the Metaphor Application
Summary
The Metaphor application is an example application with source code, builds, and GitOps delivery that showcases various features, integrations, and best practices for the Kubefirst platform. Metaphor is a useful reference to test CI changes or any other functionality you need to verify on the Kubefirst platform.
How does it work?
The Metaphor application has CI/CD that delivers each application to a development, staging, and production namespace in your Kubernetes cluster.
The Metaphor service applications' secrets in HashiCorp Vault are bound to the metaphor application through the use of the external secrets operator, a handy Kubernetes utility to keep Kubernetes secrets in sync with the Vault, the source of truth.
It demonstrates how DNS entries are automatically created in AWS Route 53 using external DNS, and has auto-renewing, short-lived certificates generated by cert-manager and the Let's Encrypt cluster-issuer.
As a demonstration space for application best practices, engineers can easily discover good patterns to use in other projects.
You can check out the main metaphor repository here.
Metaphor CI/CD
The Metaphor application includes complete CI/CD processes. It contains automated builds, container Helm chart creation, container and Helm chart publishing, linting, tests, GitOps deployments to development
, staging
, and production
namespaces, release management, version management, and hotfixes. It serves as an excellent proving ground for changes to the CI/CD layer.
When a new version of the CI is needed, it's best to adopt that new version of the CI in Metaphor first. This allows you to run through the adjustments to your automation and test it in all of the environments and Kubernetes clusters without impacting the applications that your engineers and users depend on.
CI/CD Definitions
These are the key files/folders to replicate if you want to use Metaphor in your application:
.argo
.github
chart/Metaphor
build
.gitlab-ci.yaml
- Workflow: If you are using GitHub (local or cloud), it triggers based on
.github/workflows/
. If you are using GitLab, it triggers based on the.gitlab-ci.yaml
. The idea is that these are used for simply triggering an Argo Workflows. - CWFTs: By using Argo Workflows to drive your CI jobs you can re-use some of the CWFT we provide and also create your own CWFTs to help build your toolset. The idea here is to have more generic automation that is not bound to a specific-git provider tool.
- Reuse CWFTs: Use our CWFTs as the basis to build your library of automation by adding new ones that fit your application needs.
- Dockerfile: Application is built from a Dockerfile that is defined based on the build folder.
CI Stages
Metaphor has 5 CI stages defined in the .gitlab-ci.yml
file. View the details in the directory here.
- branch: branch jobs run when your branch pushes to origin and report status to your merge requests
- publish: publishes your Docker container to ECR and publishes your prerelease chart to ChartMuseum
- development: sets the desired chart version for development
- staging: sets the desired chart version for staging
- release: publishes a release chart, sets the desired chart version for production, and patches chart in source for the next release
Argo CD is the GitOps tool responsible for auto syncing the desired state in each environment. It follows a pull model so our CI/CD ecosystem doesn't need to know how to connect to our Kubernetes clusters. We have metaphor set up to run its automation by invoking argo-workflows. Those submitted workflows can be found in the .argo directory of the repository.
Other Configuration Details
Metaphor and Helm
We provide a sample application that is packed with Helm, but it is not required. If you want to use Helm, we show you how to handle chart update flows based on Helm charts and GitOps.
Take a closer look at the files located in the chart\Metaphor
directory. There is a CWFT
that is built to bump a chart version and update chart museum. This automation shows how to leverage the tooling already embedded in Kubefirst to serve applications internally.
Ingress Integrations
The Ingress manifest demonstrates integration with our automated approach to DNS management, load balancer management, and TLS/SSL certificate creation and renewal.
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
annotations:
kubernetes.io/ingress.class: nginx
# Change the next line to "letsencrypt-staging" while testing adjustments, change to "letsencrypt-prod" after confirming LE certificate was issued
cert-manager.io/cluster-issuer: "letsencrypt-prod"
name: metaphor
labels:
run: metaphor
spec:
rules:
- host: metaphor-development.your-company.io
http:
paths:
- backend:
serviceName: metaphor
servicePort: 3000
path: /
tls:
- secretName: metaphor-tls
hosts:
- metaphor-development.your-company.io
Helpful Automation
For AWS Cloud (kubefirst create --cloud aws
):
- the value specified in
spec.rules.host
automatically creates a Route 53 CNAME that is bound to the Ingress elastic load balancer. - The
cert-manager.io/cluster-issuer
annotation promptscert-manager
to automatically create a certificate for your application and stores that cert in thesecretName
specified. - Nginx automatically routes traffic to the
metaphor
applications service based on the path-based/host-based routing specified inspec.rules
.
For a local setup (kubefirst local
):
- A local DNS route is produced with SSL certificates already generated
- This certificate can be added to your machine truststore to allow a smoother experience
Datadog Integrations
Metaphor is set up to provide cloud and container observability and monitoring best practices with Datadog. It demonstrates using Datadog for metaphor
application logs, container statistics, application metrics, application performance monitoring, dashboard, and alerting.
Secrets Management
Metaphor leverages HashiCorp Vault for secrets management. Vault runs in the mgmt
cluster and metaphor runs in preprod
and production
, so it serves as an example for secrets management.
Environment Configurations and Secrets
Metaphor includes a working example of how to leverage a multi-environment secrets management paradigm powered by Vault and external-secrets
.
There is also a ConfigMap implementation to demonstrate how to leverage non-sensitive configuration values.
Tips for Using Metaphor
Metaphor and Local - Special Attention
If you want to use Metaphor as the base of your application, and bring a new application to a local installation there is additional configuration required. We use user accounts
for local, so you will need to add a GitHub runner deployment for the new application repository.
Reference: runnerdeployment.yaml
At your gitops
repository go to components/github-runner/runnerdeployment.yaml
and clone this file, then update the property spec.template.spec.repository
to point to your-user/your-repo
. This deploys a new set of runners to observe that repository for you, allowing CI triggers to be executed.
...
spec:
replicas: 1
template:
spec:
repository: <your-user>/<your-repo>
...
Can I add gates to prevent metaphor to move between development to production?
Yes, our current approach is to self-unfold to all environments. This enables you to test your cluster with minimal steps. You can create and add a logic on the deployment artifacts to hold until a giving situation is satisfied.
Be aware of the following artifacts in your gitops
repository. Both metaphor
and your applications are likely to be added for deployment in these specific directories/environments.
- components/development
- components/staging
- components/production
Get Help with Metaphor
And as always if you have specific questions on working with Metaphor we're happy to help. Reach out to us on Slack.
Our #helping-hands
channel is monitored by our team to help address questions and troubleshoot any issues you have.