Cartographer Conventions

Conventions allow an operator to define cross cutting behavior that are directly relevant to the developer's intent. Conventions reduce the amount of manual configuration required to run applications on Kubernetes effectively.

• Pre-requisites
• Install
  • From Source
• Install on AWS
• Samples
• Contributing
• License

Pre-requisites

This project requires access to a container registry for fetching image metadata. It will not work for images that have bypassed a registry by loading directly into a local daemon.

Install

From Source

We use Golang 1.21+ and ko to build the controller, and recommend kapp to deploy.

1. Install cert-manager

   kapp deploy -n kube-system -a cert-manager -f dist/third-party/cert-manager.yaml

2. Create a namespace to deploy components, if it doesn't already exist

   kubectl create ns conventions-system

3. Optional: Trust additional certificate authorities certificate

   If a PodIntent references an image in a registry whose certificate was not signed by a Public Certificate Authority (CA), a certificate error x509: certificate signed by unknown authority will occur while applying conventions. To trust additional certificate authorities include the PEM encoded CA certificates in a file and set following environment variable to the location of that file.

   CA_DATA=path/to/certfile # a PEM-encoded CA certificate

4. Build and install Cartographer Conventions

   kapp deploy -n conventions-system -a conventions \
     -f <( \
       ko resolve -f <( \
         ytt \
           -f dist/cartographer-conventions.yaml \
           -f dist/ca-overlay.yaml \
           --data-value-file ca_cert_data=${CA_DATA:-dist/ca.pem} \
         ) \
     )

   Note: you'll need to export KO_DOCKER_REPO=<ACCESSIBLE_DOCKER_REPO> such that ko can push to the repository and your cluster can pull from it. Visit the ko README for more information.

Running cartographer convention on an AWS cluster

In order to attach an IAM role to the service account that the controller uses, provide the role arn during installation phase.

kapp deploy -n conventions-system -a conventions \
  -f <( \
    ko resolve -f <( \
      ytt \
        -f dist/cartographer-conventions.yaml \
        -f dist/ca-overlay.yaml \
        -f dist/sa-arn-annotation-overlay.yaml \
        --data-value-file ca_cert_data=${CA_DATA:-dist/ca.pem} \
        --data-value aws_iam_role_arn="eks.amazonaws.com/role-arn: arn:aws:iam::133523324:role/role_name"
      ) \
  )

The service account cartographer-conventions-controller-manager would have the role arn added as annotation

apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/component: conventions
  name: cartographer-conventions-controller-manager
  namespace: conventions-system
  annotations:
    eks.amazonaws.com/role-arn: 'eks.amazonaws.com/role-arn: arn:aws:iam::133523324:role/role_name'

Samples

• Convention Server

  Apply custom conventions to workloads with a ClusterPodConvention pointing at a webhook convention server.

• Spring Boot Conventions

  Apply custom conventions for Spring Boot workloads. This convention can detect if the workload is built from Spring Boot adding a label to the workload indicating the framework is spring-boot, and an annotation indicating the version of Spring Boot used.

• Dumper Server

  Log the content of the webhook request to stdout. Useful for capturing the image metadata available to conventions.

Contributing

The Cartographer project team welcomes contributions from the community. If you wish to contribute code and you have not signed our contributor license agreement (CLA), our bot will update the issue when you open a Pull Request. For any questions about the CLA process, please refer to our FAQ. For more detailed information, refer to CONTRIBUTING.md.

License

Refer to LICENSE for details.