k3d - Metaphor

The metaphor application is an example application with source code, builds, and GitOps delivery used to showcase various features, integrations, and best practices of the kubefirst platform. It's useful to keep on your new platform as a place to test CI changes or anything you need to verify on the platform. The metaphor app 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.

Best Practices

The metaphor applications provide a demonstration space for application best practices in a tangible way that's easy to apply to other projects. When engineers discover good patterns to use in other projects, they can add that new idea in the most straightforward way possible to the Metaphor applications as well. By doing so our engineering team can fully engage with the best application approaches.

CI/CD

The metaphor applications come with complete CI/CD processes including 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 our CI is needed, it's best to adopt that new version of the CI in a metaphor application first. Run through the adjustments to your automation and test it through all of your environments and Kubernetes clusters without impacting the applications that your engineers and users depend on.

Kubernetes Representations

The metaphor applications are multi-instance load balanced applications. It's deployed to the development, staging, and production namespaces in your kubefirst cluster.

The Kubernetes manifests produced by the metaphor applications CI include a working example of a Kubernetes deployment with downstream ReplicaSet and pods, a service account with a security context used, a service to make the application available to the cluster, and an Ingress to make the service available outside the cluster.

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

Some Cool Automated Things to Note

For an AWS Cloud selection(kubefirst create --cloud aws):

• the value specified in spec.rules.host will automatically create a route53 CNAME that is bound to the Ingress elastic load balancer.
• The cert-manager.io/cluster-issuer annotation will prompt cert-manager to automatically create a certificate for your application and will store that cert in the secretName specified.
• Nginx will automatically route traffic to the metaphor applications service based on the path-based/host-based routing specified in spec.rules.

For a local selection(kubefirst local):

• A local DNS route will be produced with SSL certificates generated for you
• This certificates can be added to your machine truststore to allow a more smooth experience

Environment Configurations and Secrets

The metaphor applications also include 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.

Datadog Integrations

The metaphor applications are 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

The metaphor applications 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. To read more see our Vault documentation.

How its CI/CD is defined

These are the key files/folders to be replicated in case, you want to use metaphor to your application:

.argo
.github
chart/Metaphor
build
.gitlab-ci.yaml

• Concept 1: If you are using GitHub (local or cloud), it will be trigger based at .github/workflows/; Or if you are using GitLab, installation, it will be trigger based at .gitlab-ci.yaml. The idea is that these are used for simply triggering an Argo Workflows.
• Concept 2: 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 automations that are not bound to a given git provider tool.
• Concept 3: Use our CWFTs as the basis to build your library of automations by adding new ones that fit your application needs.
• Concept 4: Application is build from a Dockerfile that is defined on the build folder.

Metaphor and Helm

We provide a sample application that is packed with Helm, you don't need to use Helm. if you want to use it, we show how to handle charts update flow based on Helm charts and GitOps.

The files you be interested are:

chart/Metaphor

There is a CWFT meant to bump a chart version and update chart museum. This automation is to guide how to leverage the tooling already embedded on kubefirst to serve applications internally.

Wrapping up

Here is described how metaphor gives you a demo of most of the tooling added to your cluster once the installation is finished. It is added in a way that self-unfold once the cluster is ready.

Want to learn more, check:

• GitOps
• Vault

Tips

Metaphor and Local - Special Attention

If you want to use it as base of your application, and bring a new application to a local installation. Be aware, as we use user accounts for local, you need to add a GitHub runner deployment for that 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 will deploy 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, the idea of our current approach of self-unfold to all environments it is to allow you to test the tires of your cluster with minimal need of clicks on the UI, but yes you can create and add a logic on the deployment artifacts to hold until a giving situation is satisfied.

You want to be aware of this artifacts at your gitops repository, where the metaphor and your applications probably will be added to be deployed on this giving environments.

• components/development
• components/staging
• components/production