Skip to main content

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 prompts cert-manager to automatically create a certificate for your application and stores that cert in the secretName specified.
  • Nginx automatically routes traffic to the metaphor applications service based on the path-based/host-based routing specified in spec.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.